Estimated reading time: minutes
Build the Theme
Follow these instructions to build the theme.
1. Download the theme
First download or clone the theme from the Github repo. Most likely you won’t be pulling in updates once you start customizing the theme, so downloading the theme (instead of cloning it) probably makes the most sense. In Github, click the Clone or download button, and then click Download ZIP.
2. Install Jekyll
If you’ve never installed or run a Jekyll site locally on your computer, follow these instructions to install Jekyll:
3. Install Bundler
In case you haven’t installed Bundler, install it:
gem install bundler
You’ll want Bundler to make sure all the Ruby gems needed work well with your project. Bundler sorts out dependencies and installs missing gems or matches up gems with the right versions based on gem dependencies.
4. Option 1: Build the Theme (without the github-pages gem)
Use this option if you’re not planning to publish your Jekyll site using Github Pages.
Bundler’s Gemfile specifies how project dependencies are managed. Although this project includes a Gemfile, this theme doesn’t have any dependencies beyond core Jekyll. The Gemfile is used to list gems needed for publishing on Github Pages. If you’re not planning to have Github Pages build your Jekyll project, delete these two files from the theme’s root directory:
If you’ve never run Jekyll on your computer (you can check with
jekyll --version), you may need to install the jekyll gem:
gem install jekyll
Now run jekyll serve (first change directories (
cd) to where you downloaded the project):
4. Option 2: Build the Theme (with the github-pages gem)
If you are in fact publishing on Github Pages, leave the Gemfile and Gemfile.lock files in the theme.The Gemfile tells Jekyll to use the github-pages gem. However, note that you cannot use the normal
jekyll serve command with this gem due to dependency conflicts between the latest version of Jekyll and Github Pages (which are noted briefly here).
You need Bundler to resolve these dependency conflicts. Use Bundler to install all the needed Ruby gems:
Then always use this command to build Jekyll:
bundle exec jekyll serve
If you want to shorten this long command, you can put this code in a file such as jekyll.sh (on a Mac) and then simply type
. jekyll.sh to build Jekyll.
Running the site in Docker
You can also use Docker to directly build and run the site on your local machine. Just clone the repo and run the following from your working dir:
docker-compose build --no-cache && docker-compose up
The site should now be running at http://localhost:4000/.
This is perhaps the easiest way to see how your site would actually look.
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 usually remains the same, because it allows users to navigate across products. But the sidebar navigation adapts to the product.
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 last_updated: July 3, 2016 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: mydoc_sidebar permalink: mydoc_alerts ---
sidebar: mydoc_sidebar refers to the _data/sidebars/mydoc_sidebar.yml file.
Note that your sidebar can only have 2 levels (expand the Tag archives option to see an example of the second level). 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.
You can optionally turn off the sidebar on any page (e.g. landing pages). To turn off the sidebar for a page, you should set the page frontmatter tag as
If you don’t declare a sidebar, the
home_sidebar file gets used as the default because this is the default specified in the config file:
- scope: path: "" type: "pages" values: layout: "page" comments: true search: true sidebar: home_sidebar topnav: topnav
If you want to set different sidebar defaults based on different folders for your pages, specify your defaults like this:
- scope: path: "pages/mydoc" type: "pages" values: layout: "page" comments: true search: true sidebar: mydoc_sidebar topnav: topnav
This would load the
mydoc_sidebar for each file in pages/mydoc. You could set different defaults for different path scopes.
For more detail on the sidebar, see Sidebar navigation.
The top navigation works just like the sidebar. You can specify which topnav data file should load by adding a
topnav property in your page, like this:
Here the topnav refers to the _data/topnav.yml file.
Because most topnav options will be the same, the _config.yml file specifies the topnav file as a default:
- scope: path: "" type: "pages" values: layout: "page" comments: true search: true sidebar: home_sidebar topnav: topnav
The sidebar data file uses a specific YAML syntax that you must follow. Follow the sample pattern shown in the theme, specically looking at mydoc_sidebar.yml as an example: Here’s a code sample showing all levels:
entries: - title: sidebar product: Jekyll Doc Theme version: 6.0 folders: - title: Overview output: web, pdf folderitems: - title: Get started url: /index.html output: web, pdf type: homepage - title: Introduction url: /mydoc_introduction.html output: web, pdf - title: Release Notes output: web, pdf folderitems: - title: 6.0 Release notes url: /mydoc_release_notes_60.html output: web, pdf - title: 5.0 Release notes url: /mydoc_release_notes_50.html output: web, pdf - title: Tag archives output: web folderitems: - title: Tag archives overview url: /mydoc_tag_archives_overview.html output: web subfolders: - title: Tag archive pages output: web subfolderitems: - title: Formatting pages url: /tag_formatting.html output: web - title: Navigation pages url: /tag_navigation.html output: web - title: Content types pages url: /tag_content_types.html output: web
subfolder must contain a
output property. Each
subfolderitem must contain a
The two outputs available are
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.
Each level must have at least one topic before the next level starts. You can’t have a second level that contains multiple third levels without having at least one standalone topic in the second level. If you need a hierarchy that has a folder that contains other folders and no loose topics, use a blank
- item like this:
entries: - title: sidebar product: Jekyll Doc Theme version: 6.0 folders: - title: Overview output: web, pdf folderitems: - - title: Release Notes output: web, pdf folderitems: - title: 6.0 Release notes url: /mydoc_release_notes_60.html output: web, pdf - title: 5.0 Release notes url: /mydoc_release_notes_50.html output: web, pdf - title: Installation output: web, pdf folderitems: - title: About Ruby, Gems, Bundler, etc. url: /mydoc_about_ruby_gems_etc.html output: web, pdf - title: Install Jekyll on Mac url: /mydoc_install_jekyll_on_mac.html output: web, pdf - title: Install Jekyll on Windows url: /mydoc_install_jekyll_on_windows.html output: web, pdf
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 folderitems: - 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.
Relative links and offline viewing
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.
When you write pages, include these same frontmatter properties with each page:
--- title: "Some title" tags: [sample1, sample2] keywords: keyword1, keyword2, keyword3 last_updated: Month day, year summary: "optional summary here" sidebar: sidebarname permalink: 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
keywords get populated into the metadata of the page for SEO.
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.
permalink value should be the same as your filename and include the “.html” file extension.
For more detail, see Pages.
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.
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_dropdowns. The topnav section contains single links, while the
topnav_dropdowns section contains dropdown menus. The two sections are independent of each other.
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 (
firstname.lastname@example.org) 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: pdf-product1.sh
See the section on Generating PDFs for more details about setting the theme up for this output.
Blogs / News
For blog posts, create your markdown files in the _posts folder following the sample formats. Post file names always begin with the date (YYYY-MM-DD-title).
The news/news.html file displays the posts, and the news_archive.html file shows a yearly history of posts. In documentation, you might use the news to highlight product features outside of your documentation, or to provide release notes and other updates.
See Posts for more information.
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 ``` alert("hello"); ``` 2. Second item Some pig! 3. Third item
See the topics under “Formatting” in the sidebar for more information.
If you want to use an automated system for managing links, see Automated Links. This approach automatically creates a list of Markdown references to simplify linking.
The content here is just a getting started guide only. For other details in working with the theme, see the various sections in the sidebar.Edit me