Theme files

The programming pages theme provides the css, javascript, and Jekyll layouts necessary for GitHub Pages to generate a documentation site.

This guide describes the folder structure, layouts, and include files used by the theme.

You don’t need to understand these files in order to successfully author content. This documentation may be useful for those who wish to modify (or correct) how the theme works.

• Overview
• Jekyll configuration
  • User provided configuration
  • Theme provided configuration
• User content
• Theme content
  • Layouts and includes
  • Scripts
  • Styles
  • SVG Icons

Overview

The programming pages theme comprises the following main pieces, discussed in detail in the sections below:

├─_config.yml       / project data and config values for Jekyll
├─_data/            / svg icon definitions
├─_includes/        / liquid partials
│ ├─elements/       / html partials used in layouts
│ ├─scripts/        / js partials and libraries used in layouts
│ ├─styles/         / css used in layouts
│ │ ├─semantic-ui/  / css framework files
│ └─themes/         / css theme files
├─_layouts/         / Jekyll page layouts
└─assets/           / javascript and css aggregated files

User authored content should include a homepage and some combination of API documentation, examples, and/or guides:

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

Jekyll configuration

Jekyll expects to find global site configuration values in _config.yml.

The theme uses some configuration data values, and parameterizes some aspects of the site for the user to provide values for. A typical _config.yml may look like this:

---
project:
  name: programming pages
  owner: pixeldroid
  repo: https://github.com/pixeldroid/programming-pages
  version: 0.5.22
collections:
  guides:
    output: true
    permalink: "/:collection/:path/"
    title: Guides
    tab-order: 1
  examples:
    output: true
    permalink: "/:collection/:path/"
    title: Examples
    tab-order: 2
  layout_api:
    output: true
    permalink: "/:collection/:path/"
    title: Layout API
    tab-order: 3
highlighter: rouge
kramdown:
  footnote_backlink: "⮌"
permalink: pretty
sass:
  style: compressed
plugins:
- jemoji
- jekyll-remote-theme
remote_theme: pixeldroid/programming-pages

User provided configuration

The user should provide the following project metadata values:

• project.name : used in footer attribution — Name of the project being documented
• project.owner : used in footer attribution — Copyright author
• project.repo : used in footer attribution — Link to the project source code repo
• project.version : used in title — Project version

Theme provided configuration

The theme defines the following configuration values by default; feel free to customize them:

• collections : used by Jekyll — Collection folders to expect things like api docs, examples, and guides to live in
  • <collection>.ignore-page-order : used by the theme — Turns off relative page ordering for a collection
  • <collection>.tab-order : used by the theme — Specifies relative order for the collection tabs (lower to the left)
  • <collection>.title : used by the theme — Label used for the collection tab
• highlighter : used by Jekyll — Specifies the code hilighting engine used by GitHub Pages (Rouge), so local execution matches remote
• kramdown : used by Jekyll — Specifies configuration settings for the kramdown processor
  • footnote_backlink : used by kramdown — Label to act as a ‘return to citation’ link in footnotes
• permalink : used by Jekyll — Specifies the ‘pretty’ permalink style (see Built-in permalink styles)
• plugins : used by Jekyll — Requests enablement of the jemoji and jekyll-remote-theme plugins
• sass : used by Jekyll — Specifies compressed css when processed by the scssify filter
• remote_theme : used by the theme — Specifies the programming pages theme

User content

The user must provide a homepage as index.md.

Content for collections is optional. To provide it, simply create one or more of the following directories and add content files to them:

• _api/
• _examples/
• _guides/

Collections are not limited to these three names—see the Authoring Documentation guide to learn more.

Theme content

The programming pages theme is a layered system of Jekyll layouts and included modules.

The foundational layers are diagrammed below, illustrating what each layer builds upon, defines, and includes:

Layouts and includes

At the lowest level is the compress layout, which only removes whitespace and non-documentation comments for a smaller, cleaner file.

The first html rendering layer is the base layout, which establishes the minimal outermost html boilerplate, defining a viewport for mobile compatibility, and linking in the global css and javascript.

The primary features of the programming pages theme are brought in by the page layout, which establishes the title bar header, attribution footer, collection indices, and a pop-up modal help dialog. The title bar includes the search input and results area.

Additional layouts build upon page to implement documentation specific arrangements, like package listings, type references, example figures, etc.

Pages often utilize liquid templates to process lists of data into html. Common functionality is extracted into the various .liquid files that live in the _includes directory.

Scripts

Each of the theme features has an accompanying javascript partial that is defined under _includes/scripts and included by the page layout.

Global scripts like the jQuery and Semantic UI libraries are stored under their own folders in the _includes/ directory, are aggregated by assets/site.js, and are included by the base layout.

Styles

Programming pages uses portions of the Semantic UI framework for styling and navigation. The components used are stored under _includes/styles/semantic-ui, are aggregated by assets/site.css, and are included by the base layout.

Also under _includes/styles/ are the css customizations unique to the programming pages theme.

SVG Icons

In _data/icons/theme.yml are the svg icon definitions used by the theme, via the icon.liquid include macro.