Pages

Pages

All *.md files found under --docdir are parsed as Markdown and added to the Pages menu.

(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: ...
date: ...
author: ...
version: ...
---

Recognized fields include title, date, author, and version. title is the page title; the others 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. 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.

ssptool validate also validates page metadata.

Markdown flavor

Currently uses markdown-it default options, namely CommonMark + GFM Tables and Strikethrough.

Will probably add footnotes and wikilinks.

HTML is enabled (since: 0.4.3).

Cross-references

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

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

Future Plans

The intent is to incorporate Pages into Documents.