Guides

Documents

This document gives you an overview on how to create novem documents.

AI assisted, human approved — novem uses AI to review and keep our documentation up to date.

Novem documents let you create rich, multi-page documents from novem flavoured markdown. Embed live visualisations, reference live variables, add footnotes and references, all rendered into web pages, PDFs, and presentations.

Impatient? Check out our quick start guide.

Documents, like most other novem visuals, follow the same hierarchical folder structure that you're used to seeing. A document has a primary file content where the markdown is stored, along with supporting configuration.

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 (see below)
├── 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.

The config/type setting picks the layout your document renders in. All three share the same markdown. Switching type changes only the page geometry and flow.

  • doc (default, alias docs) — paginated A4 pages. Each {{ page }} is a sheet that can be portrait (the default) or landscape. Best for reports and anything you want to print.
  • pres — 16:9 presentation slides at PowerPoint "Widescreen" dimensions (13.333in × 7.5in). Each {{ page }} is a slide and defaults to landscape. Exporting to .pptx or PDF produces a deck that drops straight into a standard PowerPoint file.
  • blog (alias web) — one continuous flowing column with no page boxes; page breaks become visual dividers. Best for articles and on-screen reading.

Set it like any other config value:

# turn a document into a 16:9 slide deck
novem -d <name> -w config/type pres

Documents and mails share the same novem markdown foundation: the same section syntax ({{ }}), the same visualisation embedding, the same styling controls. If you're familiar with novem mails, documents will feel natural.

Documents extend mails with:

  • Multi-page support — split your document into pages with {{ page }}
  • Frontmatter — YAML metadata at the top of your document
  • Page layouts — portrait, landscape, multi-column
  • Variables — embed live values from your visualisations inline
  • Span sections — footnotes, references and inline colour styling
  • Header config — attach layout hints to headings

Creating a document is similar to other novem visuals: a HTTP PUT request to the https://api.novem.io/v1/vis/docs/DOC_NAME endpoint. Documents can also be created using any of our libraries or our web page.

# create a novem document
novem -d <name> -C

# add content from a file
cat report.md | novem -d <name>

# share publicly
novem -d <name> -w shared/public true

Note: sharing a document with public requires your novem profile itself to be public; private accounts can share with users and groups, but not with the world.

Note: A document's content is capped at 5,000,000 characters (~5 MB). See Size limits for what happens when you exceed a cap and the limits on other resources.

Every document is rendered server-side and can be downloaded as a PDF or a PowerPoint deck from its files/ folder; pres documents export as 16:9 slides that drop straight into PowerPoint:

# 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

  • API — every endpoint of the document resource.
  • Content — the document content format.
  • Novem Markdown — syntax and every section type.
  • Sections — the section grammar and common parameters.
Next
Mails