No articles match the selected filter.


This is a sample Presidium configuration file:

# Site Metadata
# - name: Site name
# _ baseurl: Optional URL to use if documentation is hosted in a subdirectory `{baseurl}`
# - footer: Footer copy
# - logo: Menu bar logo.
# - show: Hide or show article components. Defaults to true
# - external: Links to external sources
#    - authors-url: base url for article authors
# NOTE: If you have a baseurl be sure to append it to any static content path e.g.: ${baseurl}/media/images/logo.png
name: Presidium Template
#baseurl: /mysite
footer: Template Footer
logo: /media/images/logo.png

  status: true
  author: true

# Jekyll collections.
# Collections represent the top level grouping of articles for a site.
# Collections directories require a leading underscore: "./content/_{collection-name}/"

# Site Sections
# Describes the top level structure of your site
# - tile: Title for top level menu title
# - path: Path to generated article collection
# - collection: The Jekyll collection to use for generating a sub menu of articles (optional).
# - collapsed: Whether articles should show in a tree or collapsed into a single item
  - title: "Overview"
    url: "/"
    collection: overview
    collapsed: true

  - title: "Key Concepts"
    url: "/key-concepts/"
    collection: key-concepts

  - title: "Prerequisites"
    url: "/prerequisites/"
    collection: prerequisites

  - title: "Getting Started"
    url: "/getting-started/"
    collection: getting-started
    collapsed: true

  - title: "Best Practices"
    url: "/best-practices/"
    collection: best-practices

  - title: "Reference"
    url: "/reference/"
    collection: reference

  - title: "Glossary"
    url: "/glossary/"
    collection: glossary
    export-content: true

  - title: "Recipes"
    url: "/recipes/"
    collection: recipes

  - title: "Tools"
    url: "/tools/"
    collection: tools

  - title: "Updates"
    url: "/updates/"
    collection: updates

# Optional Role Filters

#  label: "Show documentation for"
#  all: "All Roles"
#  options:
#    - "Business Analyst"
#    - "Developer"
#    - "Tester"

# Optional support for versioning.
versioned: false

    sass_dir: media/css/_sass


Presidium uses to manage themes. To change the theme, navigate to /media/css/_sass and edit the _variables.scss file:

// Override any bootstrap or bootswatch variables as you need:
$brand-info: #e49134;
$navbar-default-link-hover-color: #e49033;
$navbar-default-link-hover-bg: white;

// Available Bootswatch Themes
@import 'themes/spacelab';
//@import 'themes/cosmo';
//@import 'themes/darkly';
//@import 'themes/simplex';
//@import 'themes/united';

Presidium includes the themes listed above. Uncomment the theme that you want and comment the selected one. When you call Presidium with npm start, it will pick up the change and (the hotloader) will update the styles, allowing you view the new theme after refreshing the browser window.

Note that if you want a pure spacelab theme for example, you must remove the overrides as shown above ($brand-info … etc).

The default logo image is placed and loaded from /media/images/logo.png. To update it, replace the existing file in the folder. Use the following size ratio:

260px × 124px


Articles are stored in the content directory. Associated resources, such as images, are stored in the media directory. The package.json and _config.yml files are used to configure the project.

Directory Description
./_config.yml General options to configure the project
./content Articles
./dist Rendered site data and staging area for source files
./dist/src Unrendered source files
./dist/site Rendered content
./media Various resources for the project (images, imported content, etc.)
./package.json Configuration settings

All content changes are monitored; any change triggers a regeneration of the content. After a structural change (for example, adding a sub-directory or new article) a restart is required.


Front Matter serves two purposes:

  • Indicates that the file should be included as an article in the build process
  • Allows you to set properties for your article

For example:

title: Presidium
authors: github-username
roles: Developer
status: Draft

Presidium includes the following front matter variables:

variable description
title A string representing the article or subsection title or the title of the subsection.
author A string, generally the Github username of the main author of the article.
roles A list of strings representing the appropriate roles for an article.
status A string that indicates the status of the article (draft, complete, in progress, etc.)


Every article can include an author in the front matter:

author: {author name}

Optional links to authors can be enabled by setting a base authors-url in the site config:


To hide or show authors on your generated site, enable or disable the component in the site config:

  author: true|false

User Roles

Various roles can be added to a site to allow readers to filter articles and menu items by a target audience.

This optional feature can be enabled by defining user roles in the site config.

  label: "Show documentation for role"
  all: "All Roles"
    - "Business Analyst"
    - "Developer"
    - "Tester"
    - "..."

If a role is not specified, articles default to roles.all.

Articles can have one or more roles defined in front matter:

roles: [Developer, Business Analyst]
roles: [Developer]
roles: Business Analyst


Each article can be assigned a status to track its lifecycle:

  • draft
  • review
  • published
  • retired

Statuses can be set in the site’s front matter:

status: draft|review|published|retired

To show or hide statuses on your generated site, use the following setting in the site config:

show-status: true|false

Headings & Emphasis

Heading are indicated with a hash.

Heading 1

# Heading 1

Heading 2

## Heading 2

Heading 3

### Heading 3

Use either bold, italics, or monospaced font styling for emphasis:

Italicized text

*Italicized text*

Bold text

**Bold text**

Identifiers and code

`Identifiers and code`

Bullets & Numbering

Markdown allows bullets and numbering to be nested.

Use bullets to list unordered items.


  • Sentence 1.
  • Sentence 2.
    • Nested sentence 1.
    • Nested sentence 2.
      • Double nested sentence.
* Sentence 1.
* Sentence 2.
    - Nested sentence 1.
    - Nested sentence 2.
        + Double nested sentence.


Use a numbered list for steps that should be done in order. You can number the list yourself or have Presidium do the numbering automatically:

  1. One
  2. Two
  3. Three

  4. Four
  5. Five
  6. Six
1. One
1. Two
1. Three

4. Four
5. Five
6. Six


You can link to internal articles in your repository, to external articles, or even to other semantically significant text. Any text enclosed in angle brackets will be interpreted as a link. If you want to add a description, use square brackets for the description and parenthesis for the link.

Internal link: [Presidium Authors]({{site.baseurl}}/reference/front-matter/#authors)

External link: <>

Alternative: [Presidium on Github](


In Markdown

Markdown provides a simple syntax for creating tables using hyphens and horizontal bars / pipes.

first heading second heading third heading
row 1 column 1 row 1 column 2 row 1 column 3
row 2 column 1 row 2 column 2 row 2 column 3
row 3 column 1 row 3 column 2 row 3 column 3
row 4 column 1 row 4 column 2 row 4 column 3
| first heading  | second heading | third heading  |
| row 1 column 1 | row 1 column 2 | row 1 column 3 |
| row 2 column 1 | row 2 column 2 | row 2 column 3 |
| row 3 column 1 | row 3 column 2 | row 3 column 3 |
| row 4 column 1 | row 4 column 2 | row 4 column 3 |

This can be simplified by removing extra spaces, hyphens, and bars.


Markdown tables support single-line cells. For multi-line content, use an HTML table.

Heading 1 Heading 2
Single line content.
  • Multi-
  • line-
  • content.
            <th>Heading 1</th>
            <th>Heading 2</th>
        <td> Single line content. </td>


Unusual content can be included in blockquotes, which always begin with a closed angle bracket. In these examples, the Bootstrap Glyphicons provided by Jekyll have been used to embellish the text.

This is a blockquote

  • List in blockquote


  • List in blockquote
> This is a blockquote
  - List in blockquote

> <span class=”glyphicon glyphicon-pushpin”/> **Note**!
  - List in blockquote

Other Examples



Decision Point:



Glyphs List

<span class="glyphicon glyphicon-pushpin"/>
<span class="glyphicon glyphicon-list-alt"/>
<span class="glyphicon glyphicon-tags"/>
<span class="glyphicon glyphicon-knight"/>
<span class="glyphicon glyphicon-flag"/>
<span class="glyphicon glyphicon-exclamation-sign"/>

Code Blocks

To add code blocks to your content, enclose the code with three backticks. For syntax highlighting, set the language directly after the first set of backticks. Alternatively, you can indent your code / machine output to treat it as preformatted text. For single line inline code, use a single backtick.


var N = 32;
var buffer = new ArrayBuffer(N);
var N = 32;
var buffer = new ArrayBuffer(N);


my_array = [i for i in range(0, N)]
my_array = [i for i in range(0, N)]


int * my_func(int * in) {
    return in;
int * my_func(int * in) {
    return in;


Github-flavoured Markdown supports many languages for code blocks. For a full list, go to Github.


Image Links

Fully Resolved

Put any images you want to include in the <project root>/media/images directory and reference them in the text. Note the exclamation point. The image path may be fully resolved:

![Image Name](/media/images/image.png)


Or templated using the baseurl property defined in your site config:

![Image Name]({{site.baseurl}}/media/images/image.png)

Custom Property

Or templated using a custom property defined in your site config:

images: ${site.baseurl}/media/images
![Image Name]({{site.images}}/image.png)


To include a caption, add *Caption* after an image link. For example:

![Sample Image With Caption]({{site.baseurl}}/media/images/logo.png)
*Sample Image With Caption*

Sample Image With Caption Sample Image With Caption


Tooltips display a short definition of an item. There are two ways to create tooltips:

  • Automatically from the Glossary
  • Via a link override

Automatic Tooltips

Automatic tooltips reference Glossary entries. If a Glossary article by the name of “Tooltips” exists, a tooltip will be available for the following item:


[Tooltips](# 'presidium-tooltip')

Link Override

You can use an internal article as the source of a tooltip. Presidium will use the first paragraph of the article to construct the tooltip, so you should make sure the text will work as a tooltip. Note that the text used for the demarcation of a tooltip does not need to match the article title, like this, which links to an article on templates.

[this,]({{ site.baseurl }}/best-practices/#use-article-templates 'presidium-tooltip')

Landing Page


If you want your documentation to have a landing page, edit your _config.yml, so that no section has / as its url.

Change this:

  - title: "Overview"
    url: "/"
    collection: overview
    collapsed: true

to this:

  - title: "Overview"
    url: "/overview"
    collection: overview
    collapsed: true

Create a Landing Page

In the root of ./content, add a file called index.html. The example below is an excerpt from Presidium’s landing page. Note the front matter at the top which is required for paths to be rendered correctly.


<!doctype html>
<html lang="en">
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">

Create & Resolve Links

Create links to content and resolve them by including the baseurl in the path:

    <link rel="shortcut icon" href="{{site.baseurl}}/media/images/favicon.ico" type="image/X-icon">

    <link rel="stylesheet" href="{{site.baseurl}}/media/css/presidium.css" type="text/css" media="screen"/>
<div class="presidium-landing-container container-fluid">
    <nav class="presidium-landing-header">
        <div class="logo"><img src="{{site.baseurl}}/media/images/landing/presidium-header.png" /></div>
        <ul class="links">
            <li class="link"><a href="{{site.baseurl}}/overview"><img src="{{site.baseurl}}/media/images/landing/presidium-icon.png" /><span>DOCUMENTATION</span></a></li>
            <li class="link"><a href=""><img src="{{site.baseurl}}/media/images/landing/github-icon.png" /><span>ON GITHUB</span></a></li>
            <li class="link" style="display: none"><a href="#"><img src="{{site.baseurl}}/media/images/landing/slack-icon.png" /><span>ON SLACK</span></a></li>
    <div class="presidium-landing-footer">
        <div class="credit">Brought to you by </div><a href=""><img src="{{site.baseurl}}/media/images/landing/span-footer.png" title="SPAN Digital"/></a>
        <div class="copyright"><span>©2017 SPAN Digital LLC</span></div>


Importing Documentation

The Reference section of Presidium should be reserved as a low-level reference for users. Typical components documented in the Reference section may include a client library or API specification. The process of importing documentation involves parsing a reference source and generating articles that are included in the generated site.

Where possible, reference documentation should be generated to ensure that your documentation is in sync with the system being documented.

Presidium supports the following documentation sources:

For other sources that do not yet have an importer, documentation can be embedded into references.


Presidium includes a Java-based tool (presidium-swagger, based on Swagger2Markup) to import your API’s Swagger into your Presidium documentation.

  1. Add the presidium-swagger dependency to your site’s package.json or run npm install --save presidium-swagger.
  2. Add a script that invokes the tool.
  3. Run npm run import-swagger whenever you need to update your API documentation.
    "scripts" : {
        "import-swagger" : "presidium-swagger"
    "devDependencies": {
        "presidium-core" : "#.#.#",
        "presidium-jsdoc" : "#.#.#"


$ npm run import-swagger -- -u <url> -d <path> -t <string>

The following options are available for presidium-swagger:

Option Description
-d,–directory path The destination directory in which to save the generated documentation. (Default is ‘./docs’.)
-h,–help Displays this help.
-s,–sourcepath path Swagger source path.
-t,–title string The title of your docs folder. (Default is directory name supplied with ‘-d’.)
-u,–sourceurl url URL to your Swagger Json file.


Presidium can import Java source code comments using the Presidium Doclet implementation. Imported documentation will be included in the menu and sitemap.

To import javadoc, use the presidium-javadoc package.

  1. Add the presidium-javadoc dependency to your site’s package.json.
  2. Add a generation script that parses the provided <src-path> directory and <packages> and generates Markdown in your content/_reference section.
  3. Run npm run import-javadoc-api when you need to update your source documentation.
    "scripts" : {
        "import-javadoc-api" : "presidium-javadoc -s <src-path>"
    "devDependencies": {
        "presidium-core" : "#.#.#",
        "presidium-javadoc" : "#.#.#"

The following options are available to presidium-javadoc:

Option Description
-d,–directory path The destination directory in which to save the generated documentation. (Default is ‘./docs’.)
-h,–help Displays this help.
-p,–subpackages package1:package2:... Packages to generate documentation from. (Default is all.)
-s,–sourcepath path Java source code directory.
-t,–title string Reference title. (Default is ‘javadoc’.)
-u,–url foo/bar/{title-slug} Section url. (Default is ‘reference/javadoc’.)

Alternatively, you can use the Doclet within an existing build workflow such as gradle using the javadoc-plugin.


Presidium includes a template-based tool, presidium-jsdoc, based off of Jsdoc) to import Javascript comments into your Presidium documentation.

  1. Add the presidium-jsdoc dependency to your site’s package.json or run npm install --save presidium-jsdoc.
  2. Add a script that invokes the tool.
  3. Run npm run import-jsdoc whenever you need to update your API documentation.
    "scripts" : {
        "import-jsdoc" : "presidium-jsdoc"
    "devDependencies": {
        "presidium-core" : "#.#.#",
        "presidium-jsdoc" : "#.#.#"


$ npm run import-jsdoc -- -s <path> -d <path> -t <string> -p <path>

The following options are available to presidium-jsdoc:

Option Description
-d,–directory path The path to the output directory in ./content (for example, ./content/_reference/mydocs).
-h,–help Displays this help.
-p,–path path The path from which static files are served (for example, ./media/import/mydocs). Default is ./media/jsdoc/<title>.
-s,–sourcepath path The path to the project’s source.
-t,–title string The title of the output folder. Default is the directory name supplied with -d if no package information is found.


A fallback approach to importing generated documentation is to embed documentation in an iframe. This approach is not recommended because items are not indexed or available on the main menu. However, it will work for certain cases when an importer is not yet available.

When possible, use a simple template when embedding documentation in an iframe.

To include documentation in an iframe:

  1. Generate the static site documentation for your component.
  2. Put the documentation in the /media folder so that it’s statically served. The Presidium convention is to place it under /media/import/{my-reference}.
  3. Add a reference article to the Reference section:

title: My Reference



You can create multiple Markdown files for different components as required.

© Copyright 2018 SPAN Digital

Generated on Jun 20, 2018