Reference


No articles match the selected filter.

Configuration

This is a sample Presidium configuration file:

#
# Site Metadata
#
# - name: Site name
# _ baseurl: Optional URL to use if documentation is hosted in a subdirectory `domain.com/{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

show:
  status: true
  author: true
external:
  authors-url: https://github.com/

#
# Jekyll collections.
#
# Collections represent the top level grouping of articles for a site.
# Collections directories require a leading underscore: "./content/_{collection-name}/"
#
collections:
    overview:
    key-concepts:
    prerequisites:
    getting-started:
    best-practices:
    reference:
    glossary:
    recipes:
    tools:
    updates:

#
# 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
#
sections:
  - 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
#

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

# Optional support for versioning.
versioned: false

sass:
    sass_dir: media/css/_sass

Themes

Presidium uses http://bootswatch.com/ 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


Directories

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.


Overview

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.)

Authors

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:

external:
  authors-url: https://github.com/orgs/SPANDigital/people/
external:
  authors-url: https://bitbucket.org/

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

show:
  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.

roles:
  label: "Show documentation for role"
  all: "All Roles"
  options:
    - "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
---

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

show:
    roles: true|false

Statuses

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

Scopes

Articles and sections can be marked as internal and/or external via the use of the scope tag in article front matter or the site config.

Different versions of the site may then be built using:

presidium build -s [internal|external]

The front matter looks like this:

---
scope: internal
---

Multiple scopes are used like this:

---
scope: [internal, external]
---

Sections can be assigned scope in the site config like so:

sections:
  - title: Internal API
    url: /internal-api/
    collection: internal-api
    scope: internal
    
  - title: Public Section
    url: /contact-info/
    collection: contact-info
    scope: [internal, external]

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

show:
    scope: true|false

Articles without scope will inherit from their section scope, while articles with scope will be unaffected. The table below shows how these various interactions work, and what is and isn’t included in the final site in each case.

Build Scope Section Category Article
unspecified
  • undefined : ✓
  • internal : ✓
  • external : ✓
internal
  • undefined : if section.scope.includes("internal")
  • internal : ✓
  • external : ✗
if internal_articles > 0
  • undefined : if section.scope.includes("internal")
  • internal : ✓
  • external : ✗
external
  • undefined : if section.scope.includes("external")
  • internal : ✗
  • external : ✓
if external_articles > 0
  • undefined : if section.scope.includes("external")
  • internal : ✓
  • external : ✗

External URLs

Sections can redirect to an external URL either in the same tab or a new one.

This can be done by setting the external-url in the site config like so:

sections:
  - title: External Link
    collapsed: true
    external-url:
      href: "http://www.anothersite.com"
      new-tab: true
    collection: testing
    
  - title: Another External Link
    collapsed: true
    external-url:
      href: "http://www.anothersite.com"
      new-tab: false
    collection: testing

The new-tab attribute is optional and defaults to true


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.

Bullets

  • 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.

Numbering

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

Links

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: <https://github.com/SPANDigital/presidium>

Alternative: [Presidium on Github](https://github.com/SPANDigital/presidium)

Tables

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.

In HTML

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

Heading 1 Heading 2
Single line content.
  • Multi-
  • line-
  • content.
<table>
    <thead>
        <tr>
            <th>Heading 1</th>
            <th>Heading 2</th>
        </tr>
    </thead>
    <tbody>
        <tr>
        <td> Single line content. </td>
        <td>
            <ul>
                <li>Multi-</li>
                <li>line-</li>
                <li>content.</li>
            </ul>
        </td>
        </tr>
    </tbody>
</table>

Blockquotes

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

Note!

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

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

Other Examples

TODO:

http://my/url/

Decision Point:

Example:

IMPORTANT:

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.

Javascript

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

Python

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

C

int * my_func(int * in) {
    return in;
}
```c
int * my_func(int * in) {
    return in;
}
```

Others

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


Images

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)

Baseurl

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)

Captions

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

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

[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

Configure

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">
<head>
    <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">
    <title>Presidium</title>

    <link rel="stylesheet" href="{{site.baseurl}}/media/css/presidium.css" type="text/css" media="screen"/>
</head>
<body>
<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="http://www.github.com/SPANDigital/presidium"><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>
        </ul>
    </nav>
    ...
    <div class="presidium-landing-footer">
        <div class="credit">Brought to you by </div><a href="https://www.spandigital.com"><img src="{{site.baseurl}}/media/images/landing/span-footer.png" title="SPAN Digital"/></a>
        <div class="copyright"><span>©2017 SPAN Digital LLC</span></div>
    </div>
</div>

</body>
</html>

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.


Swagger

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" : "#.#.#"
    }
}

Example:

$ 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.

Javadoc

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.


Jsdoc

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" : "#.#.#"
    }
}

Example:

$ 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.

Embed

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
---

# foo.bar

<div>
    <iframe
            src='/media/import/{my-reference}/foo/bar/package-summary.html'
    </iframe>
</div>

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


© Copyright 2018 SPAN Digital

Generated on Nov 21, 2018