Content and diagram model

A page is Markdown with metadata

Files in content/ use simple frontmatter. id, title, description, type, status, and visibility are required. related builds a semantic graph independently of visual navigation.

---
id: authentication
title: Authentication
description: How the system identifies people and decides access.
type: architecture
status: observed
visibility: public
tags: security, identity
related: authorization
source_refs: ../src/auth.ts
---

Use Configuration for an internal link. Use asset:file.ext for a published image or attachment stored in assets/.

Use the supported Markdown surface

Aurelius intentionally implements a compact, deterministic Markdown surface rather than every extension from a general-purpose parser. It supports headings from level 1 through 4, paragraphs, emphasis, strong text, inline code, strikethrough, links, fenced code blocks, tables, blockquotes, callouts, horizontal rules, and flat ordered, unordered, and task lists. Diagram and Canvas tokens must occupy their own line. Headings inside fenced code are preserved as code and are not added to the table of contents, search sections, or anchor validation.

For constructs outside that set—such as nested lists, footnotes, raw HTML, or custom Markdown extensions—prefer a simpler equivalent or an authored visual whose contract is validated separately.

Choose the right diagram surface

Architecture diagrams in diagrams/*.json are deliberately bounded to 9 nodes, 12 relationships, and 3 zones. They answer one architectural question clearly.

{{diagram:publication-flow}}

For a large operational map, use a Canvas. It accepts grouped, positioned nodes and directional edges, preserves a large coordinate space, and publishes a dedicated full-view page with pan, zoom, fullscreen, keyboard-focusable cards, and readable details.

{{canvas:documentation-lifecycle}}

Open the large Canvas example to inspect a 24-step, five-phase flow. The source uses Obsidian Canvas-style type, text, fromNode, and toNode fields inside the Aurelius diagram envelope. When migrating an Obsidian Canvas, translate the relevant groups, cards, positions, edges, descriptions, and provenance into this native JSON source.

Diagram tokens do not leak into “Copy Markdown.” Aurelius replaces each token with the diagram title, description, and semantic JSON path.

Choose who owns the layout

Aurelius provides native layout for architecture and canvas. Use native JSON when the semantic model is more important than exact composition. Use svgSource for a fixed vector, or htmlSource when an agent needs to author a complete editorial visual with its own HTML, CSS, accessible SVG, or restrained interaction.

The JSON envelope keeps kind, summary, data, and provenance independent from presentation. Aurelius isolates HTML, publishes a full view, and exposes the editable source through copy. For a faithful print fallback, provide svgSource or mark one self-contained inline SVG with data-aurelius-print-source="true"; every informative SVG inside authored HTML must satisfy the same accessible title and description contract. See All visual types for the complete registry and a full authored example.

Keep claims traceable

source_refs should point to code, contracts, or documents supporting a claim. Local paths are resolved from the site root and may use .. to cite files elsewhere in the same repository; check verifies that they exist. These provenance paths are emitted as text in the API but are not copied into dist and are not public download links. Use a stable public https:// URL when a published reader must be able to retrieve an external source.

visibility is descriptive metadata for readers and downstream tooling; it is not an access-control rule. Every Markdown file in content/ is included in HTML, search, API JSON, llms.txt, and llms-full.txt. Do not place secrets in a site, and publish internal material only behind access control supplied by the hosting environment or from a separate site/build input.