Documents

A novem document stores markdown content, configuration, assets, and sharing permissions. Its content can include tables, images, embedded plots, and references to values on other resources. The document type controls whether it renders as printed pages, slides, or a continuous article.

For a worked example, follow the document quick start.

What goes into a document

Use frontmatter for metadata such as the title, author, and date. Add a frontpage block to display that metadata as a cover, and page blocks to start content pages. Frontmatter alone does not create a cover.

The following example creates a cover, contents page, and two content pages using fictional data:

---
title: Example portfolio review
audience: Example Team
date: 2026-09-30
---

{{ header cascade: true }}
$section · $audience
{{ /header }}

{{ frontpage }}

{{ tocpage depth: 2, section: Contents }}{{ /tocpage }}

{{ page section: Markets, cols: 2 }}
## Quarterly returns {colspan: all}

The example equity allocation returned 5% this quarter.

{{ colbreak }}

The example bond allocation returned 2% this quarter.

{{ page section: Allocation }}
## Asset allocation

{{ table bars: 2, bars_max: 100 }}
| Asset class | Share |
|---|--:|
| Equity | 40% |
| Fixed income | 40% |
| Alternatives | 15% |
| Cash | 5% |
{{ /table }}

The header repeats on the content pages. $section uses the label from the current page and $audience uses the frontmatter value. cols: 2 splits the first content page into two columns, while {colspan: all} keeps its heading across the full width. On the final page, bars: 2 draws the Share column as bars on a scale of 0 to 100.

The references below describe the available blocks:

• Pages: covers, contents pages, running headers and footers, numbering, and automatic pagination.
• Layout: text columns, boxes, and page layouts defined by a theme.
• Tables: column widths, totals, colours, and charts drawn from table values.
• KPI tiles: summary figures with labels and descriptions.
• Visualisations and Images: embedded resources and uploaded images.
• Page references and Variables: page numbers resolved after pagination and inline values read from resources.
• Themes: colours, fonts, spacing, and custom CSS.

E-mails share much of the markdown syntax, but use a single flow without pages. Layout and chart support differ; each block's reference describes those differences.

Document types

Set config/type to choose how the content is laid out:

For example, to render quarterly_report as a presentation:

novem -d quarterly_report -w config/type pres

The markdown stays the same when you change the type. Check the result after switching, since content that fits an A4 page may need a different arrangement on a slide.

Creating a document

Create a document with the CLI, a client library, or the website. The examples below upload a local report.md file. Both assume you have completed the relevant client setup.

# create a novem document
novem -d quarterly_report -C

# add content from a file
cat report.md | novem -d quarterly_report

Sharing is configured separately. To make this document public:

novem -d quarterly_report -s public -C

Public sharing also requires a public novem profile. Private profiles can share with users and groups. See the document API reference for sharing endpoints and Size limits for content and asset limits.

Exporting

In the document's sidebar, choose Download PDF or Download PPTX. You can also request those files through the API. Presentation documents export as 16:9 slides.

The API commands below require a bearer token. See Authentication to obtain one, then paste it at this Bash prompt to set NOVEM_TOKEN for the commands:

read -r -s -p "Novem API token: " NOVEM_TOKEN

Download the full document or a selected page:

# download the PDF
curl -H "Authorization: Bearer $NOVEM_TOKEN" \
  https://api.novem.io/v1/vis/docs/quarterly_report/files/doc.pdf -o report.pdf

# download the PowerPoint deck
curl -H "Authorization: Bearer $NOVEM_TOKEN" \
  https://api.novem.io/v1/vis/docs/quarterly_report/files/doc.pptx -o report.pptx

# export only physical page 2
curl -H "Authorization: Bearer $NOVEM_TOKEN" \
  'https://api.novem.io/v1/vis/docs/quarterly_report/files/doc.pptx?page=2' \
  -o page-2.pptx

# render physical page 2 as a PNG
curl -H "Authorization: Bearer $NOVEM_TOKEN" \
  'https://api.novem.io/v1/vis/docs/quarterly_report/files/doc.pptx?type=png&page=2' \
  -o page-2.png

The page parameter selects physical pages, counted from one, regardless of the page numbers printed in the document.

PowerPoint exports preserve supported text, tables, and chart shapes as editable objects. Content with effects such as gradients, filters, or masks may be exported as images, as may plots with too many objects. Check the downloaded file when using custom layouts or complex charts.

Resource structure

A document exposes its content and settings as API endpoints:

quarterly_report         => Document name
├── assets               => Images and fonts used by the document
├── config               => Configuration options
│   ├── theme            => Color/logo theme
│   └── type             => Layout: doc, pres or blog
├── content              => Document content (novem markdown)
├── description          => Description (meta)
├── files                => Rendered outputs (doc.pdf, doc.pptx)
├── name                 => Display name (meta)
├── summary              => Short summary (meta)
└── shared               => Who can view the document
    ├── +org~group       => Shared with an org group
    ├── @username~group  => Shared with a user group
    └── public           => Shared with everyone

This is the simplified view. The full endpoint listing (vars, tags, threads, and notifications) lives in the document API reference.

Reference

• API — every endpoint of the document resource.
• Content — the document content format.
• Novem Markdown — the text syntax and the index of blocks.
• Blocks — the block grammar and the styling keys every block shares.