GitBook-inspired documentation theme for Jekyll

This is a documentation theme for Jekyll that takes its inspiration primarily from the visual design language of GitBook, along with elements from the Docker Documentation and tweaks to suit the personal preferences of the author. Note that this theme does not reuse any code from the sites from which it draws inspiration, and is written from first principles using Bootstrap.

This theme is designed to be highly configurable, whilst providing sensible defaults for most options in order to make it as easy as possible to get up and running quickly. See the Configuration section for details of the available settings.

Contents

Installation

GitHub Pages

If you are hosting your site on GitHub Pages then add the following line to your site's _config.yml file (as per the documentation):

remote_theme: "adamrehn/jekyll-theme-gitbook"

Other hosts (e.g. GitLab Pages)

If you are hosting your site using a service that permits the use of Gem-based themes then add the following line to your site's Gemfile:

gem "jekyll-theme-gitbook"

Also add the following line to your site's _config.yml file:

theme: "jekyll-theme-gitbook"

Configuration

Top-level Jekyll configuration

Theme configuration

All configuration data for this theme is stored under a top-level YAML key called theme-settings, which has the following structure (individual sections are explained below):

theme-settings:
  
  
  # The name of the Jekyll collection that contains the site's chapters (REQUIRED)
  collection: "categories"
  
  
  # Specifies whether navigation links should be generated for chapter index files that use the `chapter-index` layout (OPTIONAL, defaults to false)
  indices: false
  
  
  # Copyright settings for the page footer (REQUIRED)
  copyright:
    
    # The author for the copyright notice (REQUIRED, supports markdown formatting)
    author: "Site Author"
    
    # The starting year for the copyright notice (REQUIRED)
    # (The theme will automatically use the current year as the ending year for the copyright notice)
    year: 2020
    
    # The license for the copyright notice (OPTIONAL, supports markdown formatting, defaults to "All rights reserved.")
    license: "Your custom license here."
  
  
  # Override the path to the site's logo image (OPTIONAL, defaults to "/assets/images/logo.svg")
  logo: "/path/to/logo.png"
  
  
  # Override the path to the site's Open Graph image (OPTIONAL, defaults to "/assets/images/opengraph.png")
  opengraph: "/path/to/opengraph.png"
  
  
  # Favicon settings (OPTIONAL, only needed if you want to override the defaults)
  favicon:
    
    # Override the PNG version of the favicon (OPTIONAL, defaults to "/assets/images/favicon.png")
    png: "/path/to/favicon.png"
    
    # Override the SVG version of the favicon (OPTIONAL, defaults to "/assets/images/favicon.svg")
    svg: "/path/to/favicon.svg"
  
  
  # Font Awesome icon settings (OPTIONAL, only needed if you want to override the defaults)
  fontawesome:
    
    # Specify that you are providing Font Awesome through your own CSS (OPTIONAL, defaults to false)
    local: true
    
    # Specify a Font Awesome Kit URL to provide icons (OPTIONAL, defaults to none, takes precedence over "local" if both are specified)
    kit: "https://kit.fontawesome.com/xxxxxxxxxx.js"
    
    # Override individual Font Awesome icons (OPTIONAL, only needed if you want to override the defaults)
    icons:
      
      # Override the "return to top" icon (OPTIONAL, defaults to "fa-arrow-up")
      # (Incidentally, if you do have a Font Awesome Pro license then this particular icon override is highly recommended)
      top: "fa-arrow-alt-to-top"
      
      # Other icon overrides go here (see the full list of supported overrides below)
      # ...

Each key in this structure serves a specific purpose:

The following icon overrides are supported:

Icon Key Default
Navigation menu toggle button `fontawesome.icons.nav` [fa-bars](https://fontawesome.com/icons/bars?style=solid)
Table of contents icon `fontawesome.icons.contents` [fa-list](https://fontawesome.com/icons/list?style=solid)
Default chapter icon at top of page if chapter doesn't have a custom icon `fontawesome.icons.page` [fa-angle-double-right](https://fontawesome.com/icons/angle-double-right?style=solid)
Return to top icon `fontawesome.icons.top` [fa-arrow-up](https://fontawesome.com/icons/arrow-up?style=solid)
Left arrow in page navigation `fontawesome.icons.left` [fa-arrow-left](https://fontawesome.com/icons/arrow-left?style=solid)
Right arrow in page navigation `fontawesome.icons.right` [fa-arrow-right](https://fontawesome.com/icons/arrow-right?style=solid)

Front matter defaults

Once you have populated the theme configuration itself, you will likely want to use Jekyll front matter defaults to configure the metadata for your content's chapters in a clean and concise manner. The following example demonstrates a site with three chapters stored in a Jekyll collection called “sections” (since the chapter metaphor does not restrict your filesystem naming conventions), with a subdirectory to hold the pages for each chapter:

# Configure the permalinks for each category ("chapter" from the theme's perspective)
collections_dir: _collections
collections:
  categories:
    output: true
    permalink: /:path

# Use front matter defaults to supply the metadata for each category
defaults:
  -
    scope:
      path: ""
      type: "sections"
    values:
      
      # Use the "default" layout provided by the theme for all pages
      layout: "default"
  -
    scope:
      
      # This is the filesystem path for the subdirectory containing the category's pages
      path: "_collections/_categories/basic"
      
    values:
      
      # The chapter name and number are required
      chapter: "Basic"
      chapnum: 1
      
      # An icon is optional and will be displayed next to the chapter name if specified
      icon: "fas fa-school"
      
      # A blurb is optional and will be displayed if you generate a list of chapters with the `chapter-list.html` include
      blurb: "This category covers basic topics."
  -
    scope:
      path: "_collections/_categories/intermediate"
    values:
      chapter: "Intermediate"
      chapnum: 2
      icon: "fas fa-university"
      blurb: "This category covers intermediate topics."
  -
    scope:
      path: "_collections/_categories/advanced"
    values:
      chapter: "Advanced"
      chapnum: 3
      icon: "fas fa-graduation-cap"
      blurb: "This category covers advanced topics."

Site structure

Stylesheet and image assets

The theme places no requirements on the structure of sites that use it, but the default configuration values do assume a number of paths for image assets and stylesheets. If you have not overridden these paths in your site's _config.yml file or hooks then the theme uses the following defaults:

Content structure: pages

If you have structured your pages into chapter subdirectories and configured their front matter defaults in the manner described above, then there are only two front matter variables that need to be specified for each individual page:

---
title: The title of the page
pagenum: 1
---

Page content goes here.

Each page must specify both a title and a page number using the pagenum front matter variable, to allow page links to be generated correctly and to be sorted within each chapter. All other front matter variables are optional. Note that if you override the chapter or chapnum values in a page's front matter with values that differ from those specified in the front matter defaults then the values from the page's front matter will take precedence and will produce inconsistent results. For that reason, it is strongly recommended that you specify chapter and chapnum exclusively within the front matter defaults.

Content structure: chapters

Each chapter should also include an index.html file, which should specify either the chapter-index or chapter-redirect layout and nothing else:

---
layout: chapter-redirect
---

The layout you choose will determine the site's behaviour when navigating to the index for a chapter (which is resolved automatically when referencing a subdirectory's path without a trailing page path.) Choose the chapter-index layout if you would like the web browser to display a list of links to the pages in the chapter, or the chapter-redirect layout if you would like the web browser to automatically redirect to the first page in the chapter.

If you use the chapter-index layout for a chapter and the global setting theme-settings.indices is set to true then a navigation link will be generated for the chapter index.

Content structure: site root

You can specify custom content for the site's front page by providing an index.html or index.md file in the root of your site's filesystem directory. The chapter-list.html include that ships with the theme is designed for use from the site root, and generates a list of chapters for you (with per-chapter blurb values included if they were specified.)

If you do not want to have a custom front page then you can use the root-redirect layout to instruct web browsers to automatically redirect to the index of the first chapter (which may in turn redirect to the first page of that chapter if you specified that behaviour, as discussed in the previous section):

---
layout: root-redirect
---

CSS styles

If you use the theme's default settings then your site is expected to have an assets/css/style.scss file with the following contents as a minimum:

---
---
@import '{{ site.theme }}';

You can change the list of CSS files that get included in the site's <head> tag by providing your own _includes/hooks/head-posthook.html file, as described in the Hooks section below. Irrespective of whether you use the default CSS filesystem path or a custom list of paths, at least one CSS file will need to include the theme's CSS styles using the code above. You can then add your own CSS rules to augment or override the default theme styles.

Note that this theme does not ship with CSS styles for syntax highlighting code blocks, so you will need to provide your own styles for syntax highlighting if your content includes code blocks. There are a wide variety of styles available online, although be sure to check that your chosen style rules are compatible with the output of whichever markdown processor you have configured Jekyll to use.

Hooks

In addition to the configuration options discussed in the sections above, you can control the HTML output of your site by using a set of supported include files that the theme refers to as “hooks”. The default contents of these hooks are located in the theme's {_includes/hooks} subdirectory, and are used throughout the theme's default layout. To replace the contents of a given hook, simply create a file in your site's filesystem directory with the same filename (e.g. _includes/hooks/head-posthook.html) and Jekyll will automatically use your version of the file instead of the default version from the theme.

The following hooks are currently supported:

Advanced options

The theme supports the following advanced configuration options:

Copyright © 2020, Adam Rehn. Licensed under the MIT License, see the file LICENSE for details.

The following third-party libraries are bundled in the theme's source tree and are covered by their respective licenses: