Authoring documentation

Create collections of guides, examples, and API references by writing markdown files and organizing them under folders.

Use theme layouts to take advantage of parameterized display structures like package listings or guide indices.

• Content
  • Project Configuration
  • Homepage
  • Collections
• Layouts

Content

Content is authored in Markdown, optionally enhanced with icons or kramdown css extensions to leverage semantic ui styling, or Liquid tags for programmatic content.

Info
See the Markdown Sampler for examples.

Tip
To use liquid tags, ensure the file starts with at least an empty YAML front-matter block.

User-authored content is expected in the following places:

├─_config.yml       / project configuration values
├─favicon.png       / (optional) user provided browser icon
├─index.md          / user provided homepage
├─_api/             / (optional collection) user provided api reference
├─_data/            / svg icon definitions
├─_examples/        / (optional collection) user provided examples
└─_guides/          / (optional collection) user provided guides

Project Configuration

The title and attribution elements of the theme use metadata defined in _config.yml.

See the Site theme files guide for more details.

Homepage

The first page seen by a visitor to the site is defined by the contents of index.md.

This file must start with a YAML front-matter declaration, which may be empty. After that, content is up to the user.

Typically, a front-matter declaration will include at least the following:

---
layout: page
title: My project
---

Collections

Grouped documentation is called a collection by Jekyll, and can be any folder of files that is named with an underscore and listed in the site configuration (_config.yml).

Info
See the Site theme files guide for details about specifying collection folders in the site configuration file.

The programming pages theme is pre-configured for three common collections (_api, _examples, _guides). To use one or more of them, simply create the collection folder and put content markdown files inside. Missing or empty collections are ignored.

Other collections are created by adding a new folder prefixed with an underscore (_), and updating _config.yml to match. The theme supports more than three collections, or fewer, or none.

API reference

An API reference collection is for listing the constructs of the public interface of a library or service.

For a namespaced language this might look like:

foo.html     / lists Bar and Baz as objects in the foo package
foo/
    Bar.html / lists methods and properties of the Bar object
    Baz.html / lists methods and properties of the Baz object

Examples

Examples are for technical illustrations of how to implement something, ideally snippets of usable code with descriptive annotations.

Guides

Guides are for explaining the concept of a topic, providing the context to be able to understand one or more examples.

By default, guides are listed alphabetically. This can be overridden for some, or all guides, by adding the order variable with an ordinal value to the page’s front matter.

See the page layout documentation for details of the layout used by guide pages.

Layouts

The theme provides several pre-defined layouts for rendering different kinds of documentation content.

To use a layout, specify its name in the YAML front-matter of the page:

---
layout: guide-index
title: Installing the theme
---

Please see the individual layout pages for more detail:

• base

• compress

• example

• guide-index

• layout

• Overview

• page