Docs

Content

This document explains the content format, markdown extensions and page structure for novem documents.

The content file /v1/vis/docs/<id>/content expects information to be supplied in novem markdown with document-specific extensions.

Documents support YAML frontmatter at the beginning of the content file. Frontmatter is enclosed between --- delimiters and parsed as page 0 metadata.

---
title: Quarterly Performance Report
author: Analytics Team
date: January 2025
theme: novem
---

Any valid YAML key-value pairs can be used. Common fields include title, author, date, subtitle and theme.

Novem documents support standard markdown including headings, paragraphs, bold, italic, lists, code blocks, blockquotes, tables and thematic breaks.

In addition, novem extends standard markdown with:

  • _underline_ — underlines text (note: _ is underline, not italic)
  • *italic* — only * produces italic
  • **bold** — standard bold
  • ~~strikethrough~~ — strikethrough
  • ^superscript^ — superscript
  • ~subscript~ — subscript (single ~, not ~~)
  • `inline code` — inline code

Documents are split into pages using the {{ page }} section. Content before the first {{ page }} becomes page 0. Each page break starts a new page with optional layout configuration.

# Page 0 content

{{ page
orient: landscape
cols: 2
}}

# Page 1 content (landscape, 2 columns)

{{ page }}

# Page 2 content (default layout)

See the pages section for full configuration options.

Headings can carry layout configuration using a trailing {key:val} syntax:

## Regional Performance {colspan:all; clr,fg,blue-700}

This attaches metadata to the heading without displaying the config in the rendered output. Configuration entries are separated by ; and support both key:value pairs and comma-separated lists.

Like mails, novem documents use sections to embed visuals and control layout. For a full overview of the section format, see the sections overview.

Available section types:

  • Pages — page breaks with layout configuration
  • Visualisation — embed novem plots and grids
  • Variables — inline live values
  • Spans — footnotes, references and colour spans
  • Paragraph — styled text blocks
  • Callout — info, warning and error callout boxes
  • HTML — raw HTML passthrough
Next
Sections