Reference


No articles match the selected filter.

Configuration

This is a sample Presidium configuration file:

languageCode: en-us
title: "Sample Title"
copyright: Template Footer
pluralizelisttitles: false
markup:
  goldmark:
    renderer:
      Unsafe: true
    parser:
      attribute:
        block: true
  highlight:
    style: github
menu:
  Main:
  - identifier: organization-overview
    name: Organization Overview
    url: /
    weight: 1
  - identifier: solution-overview
    name: Solution Overview
    url: /solution-overview/
    weight: 2
  - identifier: technology-stack
    name: Technology Stack
    url: /technology-stack/
    weight: 3
  - identifier: tool-chain
    name: Tool Chain
    url: /tool-chain/
    weight: 4
  - identifier: dev-environment-setup
    name: Dev Environment Setup
    url: /dev-environment-setup/
    weight: 5
  - identifier: getting-started
    name: Getting Started
    url: /getting-started/
    weight: 6
  - identifier: reference
    name: Reference
    url: /reference/
    weight: 7
  - identifier: updates
    name: Updates
    url: /updates/
    weight: 8
outputFormats:
  MenuIndex:
    baseName: menu
    mediaType: application/json
  SearchMap:
    baseName: searchmap
    mediaType: application/json
outputs:
  home:
  - HTML
  - RSS
  - MenuIndex
  - SearchMap
module:
  imports:
  - path: github.com/spandigital/presidium-theme-website
enableInlineShortcodes: true
frontmatter:
  lastmod:
  - lastmod
  - :fileModTime
  - :default

Themes

Presidium provides some themes when spinning up your Presidium Site through the command line. You will see something like this when running presidium init:

Select a theme
  ✔ Presidium Theme - (Presidium's default theme)

If you already have a presidium site, you can enable your theme by adding a module in the configuration file:

module:
  imports:
    - path: <Your theme>

The default Presidium logo image is placed and loaded from the pre-configured template.

To update the site’s logo place the logo image into the static/images folder and update the site’s config logo variable as seen below logo: [path to logo]

Ideally the logo should have the following specifications 260px × 124px and can be of type: png, jpg or svg

Favicon

The default Presidium favicon image is placed and loaded from the pre-configured template.

To update the site’s favicon place the favicon image into the static/images folder and update the site’s config favIcon variable as seen below favIcon: [path to favicon]

Ideally the favIcon can be of type: png, jpg or svg, ico.

Title tag

The browser <title> tag is populated with the title provided when spinning up your Presidium Site throught the command line. You can modify it by changing the title key in the configuration file.


Directories

Articles are stored in the content directory. Associated resources, such as images, are stored in the media directory. The config.yaml file is used to configure the project.

DirectoryDescription
./config.yamlGeneral options to configure the project
./contentArticles
./staticVarious resources for the project (images, imported content, etc.)

All content changes are monitored; any change triggers a regeneration of the site.


Images

Images

Images used within the content should be placed in a static/images directory

/static/images/
    -- static/doc-workflow.png

Logos and favicons

Logos

The Logo of the site appears above the Menu Navigation.

Logos should be placed in the static/images directory.

Note: If a brand module is used the instruction above does not apply. Ensure the brand module includes the static/images directory with the logo inside.

The menu bar Logo can be configured in the config file, under params:

params:
    logo: [path to logo] either locally or from the brand module

Examples:

logo: images/logo.png  
logo: images/logo.svg

Favicons

The favicon is the symbol that appears on the tab of the site, next to the title.

Favicons should be placed in the static/images directory.

Note: If a brand module is used the instruction above does not apply. Ensure the brand module includes the static/images directory with the favicon inside.

The menu bar Logo can be configured in the config file, under params:

params: 
    favicon: [path to favicon] (either locally or from the brand module)

Examples:

favicon: images/favicon.svg  
favicon: images/favicon.ico

Front matter

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
slug: overview
url: front-matter/overview
weight: 1
authors: github-username
roles: Developer
status: Draft
---

Presidium includes the following front matter variables:

VariableDescription
titleA string representing the article or subsection title or the title of the subsection.
slugA string representing the slug for deep linking the article
urlA string representing the URL for the article
weightA number to provide ordering of articles, a higher number means the article will appear later in the section
authorA string, generally the Github username of the main author of the article.
githubA string, representing the Github username of the main author of the article.
rolesA list of strings representing the appropriate roles for an article.
statusA 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 URL in the site config:

params:
  author:
    external:
      url: https://github.com/
      newTab: false

To customize the label for authors, provide a new label in the site config:

params:
  author:
    label: Custom Label

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

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

params:
  roles:
    label: "Show documentation for"
    all: "All Roles"
    options:
      - "Business Analyst"
      - "Developers"
      - "Testers"

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

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

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

params:
  show:
    status: true|false

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 externalUrl in the site config like so:

menu:
  main:
    - identifier: external-link
      name: External Link
      url: /
      weight: 1
      params:
        externalUrl:
          href: "https://www.anothersite.com"
          newTab: true
    - identifier: another-external-link
      name: Another External Link
      url: /
      weight: 2
      params:
        externalUrl:
          href: "https://www.anothersite.com"
          newTab: false 

The newTab attribute is optional and defaults to true


Markdown

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 Page link: [Presidium Authors]({{< ref "reference/front-matter/authors.md" >}})
- Internal Anchor link: [Presidium Authors]({{< ref "reference/front-matter/#authors" >}})
- External link: <https://github.com/SPANDigital/presidium>
- Alternative: [Presidium on Github](https://github.com/SPANDigital/presidium)

Tables

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

first headingsecond headingthird heading
row 1 column 1row 1 column 2row 1 column 3
row 2 column 1row 2 column 2row 2 column 3
row 3 column 1row 3 column 2row 3 column 3
row 4 column 1row 4 column 2row 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 |

Blockquotes

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

This is a blockquote

  • List in blockquote

 Note!

  • List in blockquote

Other examples

 TODO

 http://my/url/

 Decision:

 Example:

 IMPORTANT

> **TODO**
> <span class="glyphicon glyphicon-list-alt"></span>

> <http://my/url/>
> <span class="glyphicon glyphicon-tags"></span>

> **Decision:**
> <span class="glyphicon glyphicon-knight"></span>

> **Example:**
> <span class="glyphicon glyphicon-flag"></span>

> **IMPORTANT**
> <span class="glyphicon glyphicon-exclamation-sign"></span>

Codeblocks

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;
}
```

Go

package main

import "fmt"

func main() {
    fmt.Println("hello world")
}
```go
package main

import "fmt"

func main() {
    fmt.Println("hello world")
}
```

Others

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


Images

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

Image Name

![Image Name](/images/logo.png)

Image with attributes

Sample image Sample image
{{< img src="/images/logo.png" caption="Sample image" style="width:25%;" >}}

Captions

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

Sample Image With Caption Sample Image With Caption

![Sample Image With Caption](/images/logo.png)
*Sample Image With Caption*

Tooltips

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

  • Automatic from the Glossary
  • Via 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:

TooltipsThis is an example of a Glossary entry linked to from here.
{{< tooltip "Tooltips" >}}`

You can use an internal article as the source of a tooltip. Presidium will use the first 100 words 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,Before you write any content, spend some time anticipating what tasks you need to perform and make … which links to an article on plan content development.

{{< tooltip "this," "best-practices/plan-content-development.md" >}}

Importers

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.


OpenAPI3

Presidium includes a Golang tool (presidium-oapi3 for importing your OpenAPI 3 spec into Presidium documentation.

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

Example:

$ npm run import-oapi convert -f <YOUR_API_SPEC> -o <THE_OUTPUT_DIRECTORY> -r <THE_PRESIDIUM_REFERENCE_URL>

The following options are available for presidium-oapi3:

OptionDescription
-n, --apiName stringThe name under which the generated docs will be grouped
-f, --file stringOpenAPI 3 spec file
-o, --outputDir stringThe output directory
-r, --referenceURL stringThe reference URL (default “reference”)
-h, --helphelp for convert

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 /static folder so that it’s statically served. The Presidium convention is to place it under /static/import/{my-reference}.
  3. Add a reference article to the Reference section:

---
title: My Reference
---

# foo.bar

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

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


© Copyright 2022 SPAN Digital

Generated on Jul 11, 2022