Build the Theme
The first step is to build this project. Follow these instructions, below.
1. Download the theme
Clone this Jekyll project from the Github auth-docs.
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
Use Bundler to make sure all the Ruby gems needed work well with your project. Bundler sorts out dependencies and installs missing gems.
4. Build the Theme with the github-pages gem
Use Bundler to install all the needed Ruby gems:
bundle update
Then always use this command to build Jekyll:
bundle exec jekyll serve
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/.
Configure the sidebar
There are several “products” in this Jekyll theme. A product can be an idependent theme or topic. Therefore, each product can have its own sidebar. The idea is that when users are reading documentation for a specific product/theme/topic, the sidebar navigation should be specific to that product/theme/topic.
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 specific sidebar you want that page to use. Note that products can also share sidebars. 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
---
The sidebar: mydoc_sidebar refers to the _data/sidebars/mydoc_sidebar.yml file.
Note that your sidebar can only have 2 levels. Deeper nesting goes against usability recommendations.
Turn off the sidebar
You can optionally turn off the sidebar on any page (e.g. landing pages). To turn off the sidebar for a page, set the page frontmatter tag as hide_sidebar: true.
Default sidebar
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.yml 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.
Top 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:
topnav: topnav
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
Sidebar syntax
The sidebar data file uses a specific YAML syntax that you must follow. Follow the sample pattern shown in the theme, specically looking at sample_sidebar.yml as an example: Here’s a code sample showing all levels:
entries:
- title: Sample Sidebar
product: Some Product Name
version: 1.0
folders:
- title: Folder 1
output: web, pdf
folderitems:
- title: Folder 1, Item 1
url: /folder_1_item_1.html
output: web, pdf
- title: Folder 1, Item 2
url: /folder_1_item_2.html
output: web, pdf
- title: Folder 2
output: web, pdf
folderitems:
- title: Folder 2, Item 1
url: /folder_2_item_1.html
output: web, pdf
- title: Folder 2, Item 2
url: /folder_2_item_2.html
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/or pdf. Note pdf documents will not be used in the near future, we we’ll only concentrate on web page content.
See 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: Sample Sidebar
product: Some Product Name
version: 1.0
folders:
- title: Folder 1
output: web, pdf
folderitems:
-
- title: Folder 1, Item 1
url: /folder_1_item_1.html
output: web, pdf
- title: Folder 1, Item 2
url: /folder_1_item_2.html
output: web, pdf
For more detail on the sidebar, see Sidebar navigation and YAML tutorial.
Relative links and offline viewing
This Jekyll project uses relative links throughout so that you can view the site offline and not worry about which server or directory you’re hosting it.
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
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 \.
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 pages/tags/ 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.
Where to store your documentation topics
You can store your files for each product inside subfolders and sub-sub-folders of the _pages directory. When Jekyll builds your site, it will pull the topics into the root directory and use the permalink for the URL.
For more information, see Pages and Posts.
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.
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.
Markdown
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
Hi!
3. Third item
See the topics under “Formatting” in the sidebar for more information.