Front matter


No articles match the selected filter.

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

© Copyright 2018 SPAN Digital

Generated on Sep 19, 2018