These brief instructions will help you get started quickly with the theme. The other topics in this help provide additional information and detail about working with other aspects of this theme and Jekyll.
Page Contents

Preview the site

To preview the website locally:

  1. Install Ruby and Bundler if you don’t have them already.

  2. cd to the repository directory and run the following command:

$ cd
$ bundle install

Bundler will look in the Gemfile for which gems to install. The github-pages gem includes the same version of Jekyll and other dependencies as used by GitHub Pages, so that your local setup mirrors GitHub Pages as closely as possible.

Run and view site locally

Run Jekyll using the following command:

$ bundle exec jekyll serve

Then, load http://localhost:4001/ on your browser.

NOTE: The docs part will be at http://localhost:4001/doc.

Configure the sidebar

There are several products in this theme. Each product uses a different sidebar. This is the essence of what makes this theme unique – different sidebars for different product documentation. The idea is that when users are reading documentation for a specific product, the sidebar navigation should be specific to that product. (You can read more of my thoughts on why multiple sidebars are important in this blog post.)

The top navigation remains the same, because it allows users to navigate across products. But the sidebar navigation adapts to the product.

Because each product uses a different sidebar, you’ll need to set up your sidebars. There’s a file inside _includes/custom called “sidebarconfigs.html.” This file controls which sidebar gets associated with which product. Open up this file to see its contents.

The sidebarconfigs.html file uses simple if elsif logic to set a variable that the sidebar.html file uses to read the sidebar data file. The code in sidebarconfigs.html looks like this:

{% if page.sidebar == "home_sidebar" %}
{% assign sidebar = %}

{% elsif page.sidebar == "product1_sidebar" %}
{% assign sidebar = %}

{% elsif page.sidebar == "product2_sidebar" %}
{% assign sidebar = %}

{% elsif page.sidebar == "mydoc_sidebar" %}
{% assign sidebar = %}

{% else %}
{% assign sidebar = %}
{% endif %}

In each page’s frontmatter, you must specify the sidebar you want that page to use. Here’s an example of the page frontmatter showing the sidebar property:

title: Alerts
tags: [formatting]
keywords: notes, tips, cautions, warnings, admonitions

summary: "You can insert notes, tips, warnings, and important alerts in your content. These notes are stored as shortcodes made available through the linksrefs.hmtl include."
sidebar: contrib_sidebar
permalink: /doc/en/contrib/alerts

The sidebar: contrib_sidebar refers to the _data/sidebars/mydoc_sidebar.yml file (meaning, the mydoc_sidebar.yml file inside the sidebars subfolder inside the \data folder).

If no sidebar assignment is found in the page frontmatter, the default sidebar (specified by the else statement) will be shown:

Note that your sidebar can only have 2 levels. Given that each product has its own sidebar, this depth should be sufficient (it’s really like 3 levels). Deeper nesting goes against usability recommendations.

For more detail on the sidebar, see [Sidebar navigation][sidebar_navigation.html.

The sidebar data file uses a specific YAML syntax that you must follow. Follow the sample pattern shown in the theme. For example:

- title: sidebar
  product: Jekyll Doc Theme
  version: 6.0

  - title: Overview
    output: web, pdf

    - title: Get started
      url: /index
      output: web, pdf

    - title: Introduction
      url: /mydoc_introduction
      output: web, pdf

    - title: Supported features
      url: /mydoc_supported_features
      output: web, pdf

    - title: About the theme author
      url: /mydoc_about
      output: web, pdf

    - title: Support
      url: /mydoc_support
      output: web, pdf

  - title: Release Notes
    output: web, pdf

    - title: 6.0 Release notes
      url: /mydoc_release_notes_60
      output: web, pdf

    - title: 5.0 Release notes
      url: /mydoc_release_notes_50
      output: web, pdf

Each folder or subfolder must contain a title and output property. Each folderitem or subfolderitem must contain a title, url, and output property.

The two outputs available are web and pdf. (Even if you aren’t publishing PDF, you still need to specify output: web).

The YAML syntax depends on exact spacing, so make sure you follow the pattern shown in the sample sidebars. See my YAML tutorial for more details about how YAML works.

To accommodate the title page and table of contents in PDF outputs, each product sidebar must list these pages before any other:

- title:
  output: pdf
  type: frontmatter
  - title:
    url: /titlepage
    output: pdf
    type: frontmatter
  - title:
    url: /tocpage
    output: pdf
    type: frontmatter

Leave the output as output: pdf for these frontmatter pages so that they don’t appear in the web output.

For more detail on the sidebar, see [Sidebar navigation][sidebar_navigation] and [YAML tutorial][mydoc_yaml_tutorial.html.

This theme uses relative links throughout so that you can view the site offline and not worry about which server or directory you’re hosting it. It’s common with tech docs to push content to an internal server for review prior to pushing the content to an external server for publication. Because of the need for seamless transferrence from one host to another, the site has to use relative links.

To view pages locally on your machine (without the Jekyll preview server), they need to have the .html extension. The permalink property in the page’s frontmatter (without surrounding slashes) is what pushes the files into the root directory when the site builds.

Page frontmatter

When you write pages, include these same frontmatter properties with each page:

title: "Some title"
tags: [sample1, sample2]
keywords: keyword1, keyword2, keyword3

summary: "optional summary here"
sidebar: sidebarname
permalink: /doc/en/contrib/filename.html

(You will customize the values for each of these properties, of course.)

For titles, surrounding the title in quotes is optional, but if you have a colon in the title, you must surround the title with quotation marks. If you have a quotation mark inside the title, escape it first with a backlash \.

Values for keywords get populated into the metadata of the page for SEO.

Values for tags must be defined in your _data/tags.yml list. You also need a corresponding tag file inside the tags folder that follows the same pattern as the other tag files shown in the tags folder. (Jekyll won’t auto-create these tag files.)

If you don’t want the mini-TOC to show on a page (such as for the homepage or landing pages), add toc: false in the frontmatter.

The permalink value should be the same as your filename and include the “.html” file extension.

For more detail, see [Pages][pages.html].

Where to store your documentation topics

You can store your files for each product inside subfolders following the pattern shown in the theme. For example, product1, product2, etc, can be stored in their own subfolders inside the _pages directory. Inside _pages, you can store your topics inside sub-subfolders or sub-sub-folders to your heart’s content. When Jekyll builds your site, it will pull the topics into the root directory and use the permalink for the URL.

Note that product1, product2, and mydoc are all just sample content to demonstrate how to add multiple products into the theme. You can freely delete that content.

For more information, see [Pages][pages.html].

Configure the top navigation

The top navigation bar’s menu items are set through the _data/topnav.yml file. Use the top navigation bar to provide links for navigating from one product to another, or to navigate to external resources.

For external URLs, use external_url in the item property, as shown in the example topnav.yml file. For internal links, use url the same was you do in the sidebar data files.

Note that the topnav has two sections: topnav and topnav_dropdowns. The topnav section contains single links, while the topnav_dropdowns section contains dropdown menus. The two sections are independent of each other.

Generating PDF

If you want to generate PDF, you’ll need a license for Prince XML. You will also need to install Prince. You can generate PDFs by product (but not for every product on the site combined together into one massive PDF). Prince will work even without a license, but it will imprint a small Prince image on the first page, and you’re supposed to buy the license to use it.

If you’re on Windows, install Git Bash client rather than using the default Windows command prompt.

Open up the css/printstyles.css file and customize the email address ([email protected]) that is listed there. This email address appears in the bottom left footer of the PDF output. You’ll also need to create a PDF configuration file following the examples shown in the pdfconfigs folder, and also customize some build scripts following the same pattern shown in the root:


This theme uses kramdown markdown. kramdown is similar to Github-flavored Markdown, except that when you have text that intercepts list items, the spacing of the intercepting text must align with the spacing of the first character after the space of a numbered list item. Basically, with your list item numbering, use two spaces after the dot in the number, like this:

1.  First item
2.  Second item
3.  Third item

When you want to insert paragraphs, notes, code snippets, or other matter in between the list items, use four spaces to indent. The four spaces will line up with the first letter of the list item (the First or Second or Third).

1.  First item


2.  Second item

    Some pig!

3.  Third item

See the topics under “Formatting” in the sidebar for more information.