Jekyll/Bootstrap

Jekyll/Bootstrap is a Jekyll starter project for GitHub Pages with Bootstrap baked right in.

Jekyll/Bootstrap solves the confusing task of integrating Bootstrap with Jekyll by doing the integration for you - the right way - then guiding you through the simple process of customising Bootstrap - the right way.

Jekyll is a static website generator that works seamlessly with GitHub Pages. Whilst Bootstrap is the world's most popular front-end component library. Put this all together and you get a fast, secure and highly customisable static website with free hosting.

Installation
Usage
Contributing
Credits
License

Installation

Before you begin, ensure you've installed Jekyll. Then:

$ git clone https://github.com/robertlove/jekyll-bootstrap.git
$ cd jekyll-bootstrap
$ bundle install
$ bundle exec jekyll serve

If all went well, you'll be able to view your new Jekyll/Bootstrap website locally by going to http://127.0.0.1:4000/jekyll-bootstrap/ in your browser.

Usage

Configuration

Open _config.yml and update the following configuration options:
- title
- description
- baseurl
- url
- twitter
Replace /favicon.ico with your own favicon
Replace /assets/img/image.jpg with your own image

Note: Changes to _config.yml require you to rerun $ bundle exec jekyll serve in order for the changes to take effect.

For a full list of configuration options, see Jekyll Configuration.

Customising Bootstrap

One of the biggest criticisms of Bootstrap is that it makes your website look like every other Bootstrap website out there. This criticism is borne out of ignorance. Used properly, you'll be able to customise Bootstrap to make even the pickiest designer proud of you.

The process is:

Use Bootstrap components and classes in your HTML - there are many (and many utility classes are undocumented)
Override Bootstrap's default variables in _sass/_variables.scss
Write custom styles in assets/css/style.css
Write custom scripts in assets/js/script.js

For a full list of classes - including the undocumented ones, see Bootstrap CSS

For a full list of variables, see Bootstrap SCSS Variables.

Note: Done correctly, you'll likely never get to steps 3 and 4. If you do, before continuing, have another think about the way you're architecting your front-end.

Icons

Jekyll/Bootstrap comes with Bootstrap Icons pre-installed. Use the icon include for all your icon needs. The name parameter is used to specify the icon and is required. The class parameter is used to add any additional classes for styling and is optional.

{% include icon.html name='github' class='text-danger' %}

Using Third-party Libraries

Sometimes you'll want to use third-party libraries to achieve the results you're after. For example, you might want to use Prism for syntax highlighting or Moment.js for displaying dates and times in JavaScript.

To use a third-party library:

Styles

Copy any *.css or *.scss files to the _sass folder
Rename any *.css files to *.scss (e.g. rename prism.css to prism.scss)
Open assets/css/style.css and import your SCSS file(s) (e.g. @import "path/to/prism"; - leaving out the .scss file extension)

This will compile and minify all styles into _site/assets/css/style.css.

Scripts

Copy any *.js files to the assets/js folder
Open assets/js/script.js and import your JavaScript file(s) (e.g. {% include_relative path/to/prism.js %})
Open _config.yml and add your JavaScript file(s) to the list of excludes under exclude: (e.g. - assets/js/path/to/prism.js)

This will compile (but not minify) all scripts into _site/assets/js/script.js. Jekyll doesn't support minification of JavaScript files on GitHub Pages. If you want your scripts to be minified, use the minified versions supplied by the third-party library.