jekyll-twitter-bootstrap

Jekyll Twitter Bootstrap is a Jekyll theme based on Twitter's Bootstrap framework (currently, version 5.3.0). The intent of this theme is to provide a more thorough starting point for using Jekyll and Bootstrap together.

• Author: Kenny Carlile
• Theme Version: 5.3.0.dev
• Links:
  • GitHub page for Jekyll Twitter Bootstrap theme
  • Ruby Gems page for Jekyll Twitter Bootstrap theme
• Dependencies:
  • Twitter Bootstrap 5.3.0
  • Jekyll Paginate: Default pagination generator for Jekyll.
  • Jekyll Feed: A Jekyll plugin to generate an Atom (RSS-like) feed of your Jekyll posts.

Add this line to your Jekyll site's Gemfile:

gem "jekyll-twitter-bootstrap"

And add this line to your Jekyll site's _config.yml:

theme: jekyll-twitter-bootstrap

And then execute:

$ bundle

Or install it yourself as:

$ gem install jekyll-twitter-bootstrap

To launch the local Jekyll server for testing, run:

bundle exec jekyll serve

Alternately, you can run the included server script like this:

$ ./server

You may need to make the server script executable by running $ sudo chmod +x ./server.

The following layouts are available in the _layouts/ directory (indentation denotes child of previous row):

The following includes are available in the _includes/ directory (indentation denotes child of previous row):

You can show excerpts of the N latest posts, sorted by most recent first, by using the posts_latest.html include as shown below. Change the value assigned to posts_count to alter the number of most recent posts displayed. Omitting a value for posts_count will result in all posts being displayed.

For example, to add the two most recent posts to your home page's markdown, add this below:

## Recent Posts

{% include posts_latest.html posts_count=2 %}

Components are pre-built mini-templates to which you can pass values for rendering more advanced page elements. The _layouts/example_components.html layout shows how to call them. To see these examples, you can specify the example_components layout a page's front matter like this: layout: example_components

The following components are based on the Twitter Bootstrap examples and are available in the _includes/_components/ directory:

The assets/ directory contains the following content for use in the examples and defaults provided (indentation denotes child of previous row):

This theme includes layouts and includes for:

All of those layouts ultimately use the _layouts/page_sidebar.html with Categories and Tags in the sidebar. To render components in the sidebar, add the name of the _include/ template to your page's front matter like this:

sidebar:
  - categories
  - tags

To leverage this theme's blogging functionality, you'll need to create the following files in your site's structure:

The theme's _config.yml file is well documented and contains typical Jekyll theme configuration values as well as some specific to the Jekyll Twitter Bootstrap theme. The _config.yml file includes inline comments to explain intent, default values, and usage. Please view the _config.yml file for more information regarding site and theme configuration.

Bug reports and pull requests are welcome on GitHub at https://github.com/KCarlile/jekyll-twitter-bootstrap. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.

To set up your environment to develop this theme, run bundle install.

Your theme is setup just like a normal Jekyll site! To test your theme, run bundle exec jekyll serve and open your browser at http://localhost:4000. This starts a Jekyll server using your theme. Add pages, documents, data, etc. like normal to test your theme's contents. As you make modifications to your theme and to your content, your site will regenerate and you should see the changes in the browser after a refresh, just like normal.

When your theme is released, only the files in _layouts, _includes, _sass and assets tracked with Git will be bundled. To add a custom directory to your theme-gem, please edit the regexp in jekyll-twitter-bootstrap.gemspec accordingly.

• Q: Why use Bootstrap with Jekyll?

  • A: Bootstrap provides a lot of easy utilities for formatting without having to write a lot of your own custom CSS. It's ease of use makes it a great starting point for basic sites. Combining the power of Bootstrap and Jekyll means you can get your site up and running faster while still being able to customize it as needed.

• Q: This isn't the only Bootstrap-based theme for Jekyll. What about those other ones?

  • A: At the time of creation, the other Bootstrap-based Jekyll themes didn't have the level of maturity needed or they were based on older versions of Bootstrap.

• Q: If I want my posts to be referred to as Articles (or something else) instead of Blog, how can I make that change?

  • A: There are a few steps necessary to change your post listing name from Blog to something else.
    • Rename blog/index.html to articles/index.html
    • In articles/index.html, change the name of the page from "Blog" to "Articles":

      ---
      # title: Blog
      title: Articles
      layout: blog
      sidebar:
        - categories
        - tags
      ---
      ...

      The layout can remain named blog unless you really want to override and rename the layout.
    • In your _config.yml file, change these lines from blog to article:

      ...
      # Add pages here to explicitly appear in this order in your navigation.
      header_pages:
        # - blog/index.html
        - articles/index.html
      ...
      # paginate_path: "/blog/:num"
      paginate_path: "/articles/:num"
      # Define the post permalink format.
      #permalink: /blog/:year/:month/:day/:title:output_ext
      permalink: /articles/:year/:month/:day/:title:output_ext
      ...

The theme is available as open source under the terms of the MIT License.