h5bp + twitter bootstrap integration

readme.md

Shell script to quickly setup a project using html5boilerplate and twitter bootstrap.

description

html5boilerplate + twitter bootstrap is a super combo.

Here is what I usually do to setup a project using html5boilerplate and twitter bootstrap. Following assumes a build process and relies on bootstrap's less files, it also requires both git and npm (so node too) installed and available in your path.

A single style.css file is used and h5bp's style.css is renamed to h5bp.css (not used in profit of bootstrap's css reset). Bootstrap less compile step outputs to bootstrap.css and an app.css is there to setup site's specific CSS rules.

The style.css file relies on @import, so it assumes the use of a build process, to inline and minify these import in a single file.

Bootstrap's plugins can be concat'd to js/plugins.js, you'll be prompted for each js/*.js file in the js/ dir of bootstrap's repo.

install

h5bp-twitter-bootstrap is a simple (and dumb) shell script, so you can drop it somewhere in your $PATH. It's particularly handy if you have a collection of dotfiles and bin helpers.

Relatadely, it is bundled as an npm package, so you may use npm instead to perform the install.

Through npm:

npm install https://gist.github.com/gists/1422879/download -g

usage

Just run h5bp-twitter-boostrap. You'll be prompted for

• a directory name (if not setup through dirname cli option)
• for each bootstrap's JS plugins
• by npm when the npm init is run.

Running h5bp-twitter-bootstrap -h will output usage below:

Usage:

  h5bp-twitter-bootstrap [-h] [dirname]

Directory structure

→ build
|  → config
|  → tools
→ css
|  → less
→ img
→ js
|  → libs

• Get html5boilerplate project (git clone into ./tmp/h5bp)
• Get twitter bootsrap (git clone into ./tmp/bootstrap)
• Create html5boilerplate directory/file structure by running build/createproject.sh
• Copy bootstrap's less/ folder to css/less/ (or any other path you'd like, following assumes css/less/)
• Creates an empty app.css file.
• Go in css, rename h5bp's style.css to h5bp.css.
• Create a new css/style.css file.

And adds the following:

/* =============================================================================
   CSS App imports.

   These imports are inlined and minified by the build script. If
   you don't intend to use a build script, do not use @import
   statements. Use a single style.css file with h5bp's style first,
   then bootstrap.css, then your specific CSS files.

   h5bp's style first.

   ========================================================================== */


@import url('h5bp.css');
@import url('bootstrap.css');
@import url('app.css');

• Create a new css/app.css. This file is where you'll put your site's specific CSS rules.
• Processing of bootstrap's plugins, you'll be prompted for each files in .tmp/bootstrap/js/ directory. Simply put a y/n (or yep/nope that'll work too) to tell wheter you want them included and concat'd to the js/plugins.js file.
• Inits an npm package for your website (npm init and follow instructions).
  • You may want to tweak the package.json file, add a "private": true props so that you don't accidently publish to npm registry. You may kill off any of the props except from name/version ones.
• Add less as package.json's depdendency (npm install less --save).
• Add an npm script to trigger the less build:

package.json:

{
  "name": "foobar",
  "description": "fancy description",
  "version": "0.0.1",
  "dependencies": {
    "less": "~1.2.1"
  },
  "scripts": {
    "less": "./node_modules/.bin/lessc --compress ./css/less/bootstrap.less > css/bootstrap.css"
  }
}

The command is ./node_modules/.bin/lessc --compress ./css/less/bootstrap.less > css/bootstrap.css.

• Finally, actually triggers the npm less script and compiles the css/bootstrap.css for the first time.

Once done, you may run npm run-script less to rebuild the css if needed.

bootstrap-plugins.txt

bootstrap-tooltip.js
bootstrap-popover.js
bootstrap-alert.js
bootstrap-button.js
bootstrap-carousel.js
bootstrap-collapse.js
bootstrap-dropdown.js
bootstrap-modal.js
bootstrap-scrollspy.js
bootstrap-tab.js
bootstrap-transition.js
bootstrap-typeahead.js

h5bp-twitter-bootstrap

#!/usr/bin/env bash


src=$PWD
ant_build_script_remote=git://github.com/h5bp/ant-build-script.git
h5bp_remote=git://github.com/h5bp/html5-boilerplate.git
bootstrap_remote=git://github.com/twitter/bootstrap.git

ant_build_script_branch=master
h5bp_branch=master
bootstrap_branch=2.0-wip

# list of bootstrap plugins to be prompted
PLUGINS=$(cat bootstrap-plugins.txt)

# the less cmd to run to compiles bootstrap's css files
LESS_CMDS="#!/usr/bin/env bash

mkdir css/bs/
./node_modules/.bin/lessc css/less/bootstrap.less css/bs/bootstrap.css
./node_modules/.bin/lessc css/less/responsive.less css/bs/bootstrap-responsive.css
./node_modules/.bin/lessc --compress css/less/bootstrap.less css/bs/bootstrap.min.css
./node_modules/.bin/lessc --compress css/less/responsive.less css/bs/bootstrap-responsive.min.css

# edit the few lines below to not include responsive's css into final bootstrap css

cat css/bs/bootstrap.css css/bs/bootstrap-responsive.css >> css/bootstrap.css
cat css/bs/bootstrap.min.css css/bs/bootstrap-responsive.min.css >> css/bootstrap.min.css

"

# need help ? if no args and help flags
if [ "$1" == '-h' ]
then
  cat <<EOF

  Usage:

    h5bp-twitter-bootstrap [-h] [dirname]

EOF
  exit
fi


echo "

  Cool, let's start.

"

if [ $# -eq 1 ]
then
  # get a name for new project from command line arguments
  name="$1"
fi

# get a name for new project from input
while [ -z $name ]
do
  echo "To create a new project, enter a new directory name"
  read name || exit
done

[ -d $name ] && echo "Directory $name already exists" && exit 1

echo "
  1a. Get html5boilerplate project (git clone into ./tmp/h5bp)
"

if ! [ -d .tmp/h5bp ] 
then git clone $h5bp_remote .tmp/h5bp || exit 1
fi

cd .tmp/h5bp
[ $(git branch | grep "*" | sed s/*//) != $h5bp_branch ] &&
  # not the current branch, attempt to create new branch
  git checkout -b $h5bp_branch origin/$h5bp_branch ||
  # if already created, then attempt to checkout
  git checkout $h5bp_branch

git pull && cd $src

echo "
  1b. Get h5bp/ant-build-script project (git clone into ./tmp/ant-build-script)
"

if ! [ -d .tmp/ant-build-script ]
then git clone $ant_build_script_remote .tmp/ant-build-script || exit 1
fi

cd .tmp/ant-build-script
[ $(git branch | grep "*" | sed s/*//) != $ant_build_script_branch ] &&
  # not the current branch, attempt to create new branch
  git checkout -b $ant_build_script_branch origin/$ant_build_script_branch ||
  # if already created, then attempt to checkout
  git checkout $ant_build_script_branch

git pull && cd $src

echo "
  2. Get twitter bootstrap project (git clone into ./tmp/bootstrap).
"
if ! [ -d .tmp/bootstrap ] 
then git clone $bootstrap_remote .tmp/bootstrap || exit 1
fi

cd .tmp/bootstrap
[ $(git branch | grep "*" | sed s/*//) != $bootstrap_branch ] &&
  # not the current branch, attempt to create new branch
  git checkout -b $bootstrap_branch origin/$bootstrap_branch ||
  # if already created, then attempt to checkout
  git checkout $bootstrap_branch

git pull && cd $src


echo "
  3. Create html5boilerplate directory/file structure by running build/createproject.sh
"
cd .tmp/h5bp && ../ant-build-script/createproject.sh project && cd $src
mkdir -p $name
echo "Created directory: $name"
cd .tmp/h5bp && cp -r -- css js img *.html *.xml *.txt *.png *.ico .htaccess "../../$name"
echo "Created h5bp project's structure: $name"
cd $src

echo "
  4. Copy bootstrap's 'less' folder to 'css/less/' (or any other path you'd like, following assumes 'css/less/')
"
cp -vr .tmp/bootstrap/less $name/css/less
echo "Create bootstrap's less directory in css/less"

# Commenting out the reset bootstrap drop. By default, the whole bootstrap's css files is used and h5bp's one
# is renamed into h5bp.css. The style.css file importing the css assets does not use h5bp.css.

# echo "\n5. Go in 'css/less', edit the bootstrap.less file and remove the '@import \"reset.less\";' line."
# cp $name/css/less/bootstrap.less $name/css/less/bootstrap.less.orig
# sed '/reset/d' $name/css/less/bootstrap.less.orig | sed '/Reset/d' > $name/css/less/bootstrap.less

echo "
  5. Create the app.css file
"
echo "

/* =============================================================================
   App specific CSS file.

   This is usually where the site/app's CSS specific rules are setup. Note that you could
   do exactly the same using less by adding a '@import "app.less";' at the end of
   css/less/bootstrap.less file.

   ========================================================================== */

" > $name/css/app.css

echo "
  6. Go in 'css', rename h5bp's 'style.css' to 'h5bp.css'.
"
cd $name/css && mv style.css h5bp.css && cd $src

echo "
  7. Create a new 'css/style.css' file:
"
echo "

/* =============================================================================
   CSS App imports.

   These imports are inlined and minified by the build script. If
   you don't intend to use a build script, do not use @import
   statements. Use a single style.css file with bootstrap's style first,
   then your specific CSS files.

   Following assumes an app.css to put specific CSS rules.

   Both unminified and minified version of bootstrap's css will be generated by the
   less script command. You may want to switch the bootstrap.css to bootstrap.min.css

   ========================================================================== */

@import url('bootstrap.css');
@import url('app.css');

" > $name/css/style.css

echo "
  8. Processing of bootstrap's plugins, you'll be prompted for each files in
  .tmp/bootstrap/js/ directory. Simply put a y/n to tell wheter you want them
  included and concat'd to the js/plugins.js file.

  Note that popover plugin requires tooltip to be included fist, so be sure to
  tell this script to include both tooltip / popover. You'll be prompted for
  tooltip plugin at first.
"


cd .tmp/bootstrap/js/
for f in $PLUGINS; do

  while [ "$yepnope" != "y" -a "$yepnope" != "n" -a "$yepnope" != "yep" -a "$yepnope" != "nope"  ]
  do
    read -p "$f >> $name/js/plugins.js: (yep) " yepnope || exit
    [ -z $yepnope ] && yepnope="yep"

    [ "$yepnope" == "y" -o "$yepnope" == "n" ] ||
      [ "$yepnope" == "yep" -o "$yepnope" == "nope" ] ||
      echo "Incorrect value"
  done

  [ "$yepnope" == "y" -o "$yepnope" == "yep" ] && cat $f >> $src/$name/js/plugins.js
  unset yepnope
done
cd $src


echo "
  9. Init npm package for the website
"
cd $name && npm init || exit 0

echo "You may want to tweak the package.json file, only name/version are mandatory."

echo "
  10. Add less as package.json's dependency (npm install less --save)
"
npm install less --save || exit 0

echo "
  11. Add an npm script to trigger the less build.
"
mv package.json package.json.orig
cat package.json.orig | sed "$ s/}/  , \"scripts\": { \"less\": \"sh build-bootstrap.sh\" } }/g" > package.json
echo "$LESS_CMDS" > build-bootstrap.sh
cd $src

echo "
  12. Leaving out temporary dirs (.tmp/). You may want to remove this dir or let it be so that
  next builds will pull instead of clones (significantly faster).

  This is relative to the current working directory though: $src
"


echo "
  13. Running a first compile step to generate $name/css/bootstrap.css
"
cd $name && npm run-script less || exit 0

echo "

    All done!

Check out the $name directory.

Simply run 'npm run-script less' to trigger the less compile step.

"

package.json

{
  "author": "mklabs",
  "name": "h5bp-twitter-bootstrap",
  "description": "Shell script to quickly setup a project using html5boilerplate and twitter bootstrap",
  "version": "0.0.2",
  "bin": "./h5bp-twitter-bootstrap"
}

I don't think combining the CSS is going to work that well because Bootstrap needs its reset to remove default heading margins and list padding. That is an assumption in the rest of the code (for was last time I checked), which can affect things like the topbar and tabs/pills.

Thanks necolas. My first thought was to simply replace bootstrap's css reset by h5bp's style.

I'll update this accordingly, it also cuts down a few steps. Sounds good to me :)

Cool, this ties in nicely with http://qr.ae/7aQuA

I kept getting one script error on a new install: "Uncaught TypeError: Cannot read property 'Twipsy' of undefined". Moving the Popover function to load after Twipsy in the plugins.js fixed the problem. I think the concatenation routine should probably help others avoid this:

Fix suggested by this: seyhunak/twitter-bootstrap-rails#8

Indeed, the concatenation should handle this case. popover plugin requires twipsy (or tooltips in v2) to be loaded first.

Not sure how with the prompts, but I'll try to fix this. Maybe by prompting first for popover plugin, if its a yes then include tooltip automatically and right before, if it's a no then prompt for tooltips.

Anyway, thanks for finding this!

I'm using git version 1.7.4.1 and the "git br" commands produce this error:

git: 'br' is not a git command. See 'git --help'.
Did you mean one of these?
        branch
        var
/usr/bin/h5bp-twitter-bootstrap: line 55: [: !=: unary operator expected

Changing the commands to "git branch" solves this issue.

See https://gist.github.com/1720389/

Has this script already been made compatible with Bootstrap 2.0? Step 4 seems to be failing. The css/less directory is not created on the target; /lib does not exist on bootstrap source tree. So this command seems to be doing nothing:

cp -vr .tmp/bootstrap/lib $name/css/less

@fernandoacorreia You're absolutely true. git br is an alias i'm using for git branch, I shouldn't have used it here (cause that'll most likely break).

For bootstrap v2, nope, not yet. the only thing that is possible is to change the branch to use, but the script lacks the necessary logic to act accordingly with v1 or v2. Finally, I'm wondering if just handling v2 is enough now. That'll probably end that way.

Please take a look at my fork (git://gist.github.com/1720389.git). It has 3 fixes:

• "git br"
• new directory structure for Bootstrap 2.0 ("less" directory)
• support for the new h5bp / ant-build-script project (no more build directory in html5-boilerplate)

I'll do! Thanks. That is much appreciated.

Thanks so much! One note -- when running "h5bp-twitter-bootstrap" from a different directory, it skips the "bootstrap-plugins.txt" yes/no section. I had to copy that file over to the current directory to get that to work.

Hey @kaneuniversal, glad this little script has been useful to you :) If you come with any solution that can be automated to circumvent this boottsrap-plugins.txt issue, I'll be happy to merge this back here.

mmmm . . . I'm not so familiar with bash scripting though I'll gladly contribute any tweaks I may happen to make.

One question: wouldn't it make sense to get the Bootstrap project from GitHub and then create the bootstrap-plugins list by checking the contents of its /js directory?

Just wanted to mention @elegos' version of the script. Pretty similar but the bash script seems to be better implemented as it doesn't:

mess with the already-created repository clones

I didn't checked it in details, but it is definitely worth giving it a try. I'll update the readme file to add a link to this alternate script. Thx @elegos :)

Describing my experience with this on OS/X Lion...

• Installed node.js from http://nodejs.org. no problem
• Ran npm install https://gist.github.com/gists/1422879/download -g. Failed because of access.
• Ran sudo !! (sudo of previous command). Installed fine.
• Ran h5bp-twitter-bootstrap and got fatal: could not create leading directories of '.tmp/h5bp': Permission denied. Lesson learned: One cannot run this command while in a directory they do not have write access to. (Perhaps if the script used /tmp or handled temp directories for the OS being run in.)
• cd /some/dir/i/can/write/to and got past the previous error.
• Started to lose my motivation for attempting this.
• Ran again and typed a directory that I created to hold the project. Directory already exists. Would be nice if this was a warning and not a hard stop.
• Ran again with a non-existing directory name. Passed the prompts. Got:
  1. Running a first compile step to generate /Users/sands/Experiments/H5BP+Bootstrap/Design/css/bootstrap.css

npm WARN package.json Design@0.0.0 No README.md file found!

Design@0.0.0 less /Users/sands/Experiments/H5BP+Bootstrap/Design
sh build-bootstrap.sh

mkdir: css: No such file or directory
lessc: ENOENT, open '/Users/sands/Experiments/H5BP+Bootstrap/Design/css/less/bootstrap.less'
lessc: ENOENT, open '/Users/sands/Experiments/H5BP+Bootstrap/Design/css/less/responsive.less'
lessc: ENOENT, open '/Users/sands/Experiments/H5BP+Bootstrap/Design/css/less/bootstrap.less'
lessc: ENOENT, open '/Users/sands/Experiments/H5BP+Bootstrap/Design/css/less/responsive.less'
build-bootstrap.sh: line 11: css/bootstrap.css: No such file or directory
build-bootstrap.sh: line 12: css/bootstrap.min.css: No such file or directory
npm ERR! Design@0.0.0 less: sh build-bootstrap.sh
npm ERR! sh "-c" "sh build-bootstrap.sh" failed with 1
npm ERR!
npm ERR! Failed at the Design@0.0.0 less script.
npm ERR! This is most likely a problem with the Design package,
npm ERR! not with npm itself.
npm ERR! Tell the author that this fails on your system:
npm ERR! sh build-bootstrap.sh
npm ERR! You can get their info via:
npm ERR! npm owner ls Design
npm ERR! There is likely additional logging output above.

npm ERR! System Darwin 11.4.0
npm ERR! command "node" "/usr/local/bin/npm" "run-script" "less"
npm ERR! cwd /Users/sands/Experiments/H5BP+Bootstrap/Design
npm ERR! node -v v0.8.8
npm ERR! npm -v 1.1.59
npm ERR! code ELIFECYCLE
npm ERR!
npm ERR! Additional logging details can be found in:
npm ERR! /Users/sands/Experiments/H5BP+Bootstrap/Design/npm-debug.log
npm ERR! not ok code 0

• Realize the Bootstrap branch 2.0-wip no longer exists. Update with 2.1.1-wip.
• After much confusion, realize that .tmp isn't being cleaned up and git is failing with overwrite warnings. rm -rf .tmp
• Seeing usage: cp [-R [-H | -L | -P]] [-fi | -n] [-apvX] source_file target_file
cp [-R [-H | -L | -P]] [-fi | -n] [-apvX] source_file ... target_directory related to the line cd .tmp/h5bp && cp -R -- css js img *.html *.xml *.txt *.png *.ico .htaccess "../../$name"
• Tried 10 variations on the cp command and pored over man cp and cursed a lot.
• Split out each directory copy onto its own line.
• Now it's trying to copy to the absolute path with "../.." prepended. Remove all of those. Promise self to give up if next step doesn't work.
• Copies succeed but still getting lessc: ENOENT, open '/Users/sands/MIT/Experiments/H5BP+Bootstrap/Design17/css/less/bootstrap.less'
lessc: ENOENT, open '/Users/sands/MIT/Experiments/H5BP+Bootstrap/Design17/css/less/responsive.less'
lessc: ENOENT, open '/Users/sands/MIT/Experiments/H5BP+Bootstrap/Design17/css/less/bootstrap.less'
lessc: ENOENT, open '/Users/sands/MIT/Experiments/H5BP+Bootstrap/Design17/css/less/responsive.less'
cat: css/bs/bootstrap-responsive.css: No such file or directory
cat: css/bs/bootstrap-responsive.min.css: No such file or directory
npm ERR! Design17@0.0.0 less: sh build-bootstrap.sh
npm ERR! sh "-c" "sh build-bootstrap.sh" failed with 1
npm ERR!
npm ERR! Failed at the Design17@0.0.0 less script.
npm ERR! This is most likely a problem with the Design17 package,
npm ERR! not with npm itself.
npm ERR! Tell the author that this fails on your system:
npm ERR! sh build-bootstrap.sh
npm ERR! You can get their info via:
npm ERR! npm owner ls Design17
npm ERR! There is likely additional logging output above.

npm ERR! System Darwin 11.4.0
npm ERR! command "node" "/usr/local/bin/npm" "run-script" "less"
npm ERR! cwd /Users/sands/MIT/Experiments/H5BP+Bootstrap/Design17
npm ERR! node -v v0.8.8
npm ERR! npm -v 1.1.59
npm ERR! code ELIFECYCLE
npm ERR!
npm ERR! Additional logging details can be found in:
npm ERR! /Users/sands/MIT/Experiments/H5BP+Bootstrap/Design17/npm-debug.log
npm ERR! not ok code 0 at the end.

• Get pissed that I wasted so much time on this and exit

One more step:

• Goes to http://www.initializr.com and nearly screams when it works within 30 seconds. sigh

is it working with the current version of bootstrap 3.0? Thanks