Build the Theme

Follow these instructions to build the theme.

Comments

The theme integrates Commento.io for comments below pages and posts. (This commenting service doesn’t inject controversial tracking ads like Disqus does.) You will need to Commento.io account + plan ($5/month) to authorize Commento with your domain (no other configuration should be required). If you don’t want comments, in the _config.yml file, change the comments: true properties (under defaults) to comments: false in every instance. Then in the commento.html include file (inside _includes), the {% unless page.comments == false %} ... {% endunless %} logic will not insert the Commentio form.

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.

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][main_pages] and [Posts][main_posts].

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

    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][main_hyperlinks.html#automatedlinks]. This approach automatically creates a list of Markdown references to simplify linking.

Other instructions

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.

Tags: getting_started