Pages

Pages

All *.md files found under --docdir are parsed as Markdown and added to the Pages menu. Pages may be incorporated into Documents.

(The default --docdir is ./markdowns, following compliance-masonry conventions.)

Front-matter metadata

Markdown files may include YAML metadata at the beginning of the file, delimited by lines consisting of three dashes:

---
title: ...
author: ...
date: ...
last_modified: ... (since 0.4.6)
version: ...
---

Recognized fields include title, author, date, last_modified, and version, as well as component metadata fields (see below).

title is the page title; the other headers will be displayed in the page identification section.

Pages as Components

(Since: 0.4.2)

Pages also provide a simplified way to define Components. If the front matter contains a satisfies header like:

satisfies:
  standard_1:
    control_1: description   # short form
    control_2:
      key_1: ...             # narrative form
      key_2: ...
implementation_status: _status_

this will define the page as a Component that satisfies the indicated controls with the associated narratives. Other component metadata headers include:

• component: component name (default taken from page ID)
• system
• implementation_status
• responsible_role The same implementation_status is inherited by all satisfaction records.

This is more concise than the full component.yaml syntax, and can be used to keep component metadata attached to its documentation. Recognized component metadata

ssptool validate also validates page metadata.

Markdown flavor

Currently uses markdown-it default options (CommonMark plus GFM Tables and Strikethrough), with the following extensions:

• HTML is enabled (since: 0.4.3)
• wikilinks (since: 0.5.0)

Cross-references

Pages are identified by their pathname relative to --docdir, including the .md extension.

NOTE this is not set in stone and may be revised in future. Considering using the file stem (basename minus extension and directory) as the primary key instead.

Heading levels

The default page template uses H1 for the page title. Page contents should generally use H2 and above.

Rendering

The following data is available to the template system:

• page.html - HTML rendering of page contents
• page.data - frontmattter metadata