Requirements for transforming the Obsidian vault into a published website, such that the site matches the vault as closely as reasonably possible.
Captured 2026-02-27; updated 2026-03-17. See also: [Content Graph Architecture](Content Graph Architecture.md).
Core requirement: relationship navigation
The primary unmet requirement is rendering dynamic navigation links derived from the vault’s three relationship types. At the bottom of each note that participates in one or more relationships, the published page must show the relevant link lists.
Pending implementation
Relationship traversal rendering is not yet implemented in the Quartz build. See [Content Graph Architecture](Content Graph Architecture.md) for the planned approach.
Relationship types
| Property | Direction | Semantics |
|---|---|---|
isIn | upward | physical containment (area → area, device → area, device → device) |
partOf | upward | functional membership (device → system, system → system) |
dependsOn | upward (array) | infrastructure dependencies; always an array |
Parent trail rendering
- Traverse upward from the current note to the root (a note with no parent in that relationship type).
- Render as a linked trail, e.g.:
Duplex > Unit B > Master Bedroom B - When a note on the trail participates in more than one relationship type, the trail forks at that point. Each fork continues upward in its own relationship type. Render the relationship type in parentheses at the start of each forked branch.
- Example of a forked trail:
(isIn) Duplex > Unit B > Master Bedroom B > [current note](partOf) Electrical > Circuit 4 > [current note]
Child list rendering
- List all notes that name the current note as their parent in a given relationship type.
- When a child participates in more than one relationship type pointing to different parents, a similar fork / label scheme applies (details TBD).
Sibling list rendering
- List all notes that share the same parent as the current note in a given relationship type (i.e., same-level nodes in the same hierarchy branch).
Ordered members (prev / next)
Some objects are members of an ordered list within a relationship. Examples:
- Receptacles on an electrical circuit (ordered by circuit position)
- Sprinkler heads of an irrigation zone (ordered by zone sequence)
For these, render previous and next links in addition to the sibling list. The ordering
mechanism is TBD (likely a numeric frontmatter property or explicit next/prev links).
Publishing pipeline requirement
The publishing workflow must:
- Trigger automatically on every push to the GitHub repository.
- Build the static site without manual intervention.
- Deploy to Cloudflare Pages (current setup) or equivalent CDN.
- Require no paid hosting beyond what is already in use.
The current GitHub Actions → Quartz build → Cloudflare Pages pipeline meets this requirement.
Rendering compatibility
The publishing solution must render:
- Standard Markdown (headings, lists, tables, code blocks, blockquotes)
- Mermaid diagrams (
```mermaidfences) - Standard Markdown links:
[label](path/to/note.md) - Standard Markdown images:
 - Frontmatter properties (used for relationship traversal and metadata display)
The following are local-only features used in Obsidian but not required on the published site:
- Obsidian Bases (
.basefiles) — Obsidian-native; not published - Obsidian Canvas (
.canvasfiles) — not published
Candidate solutions
| Solution | Status | Notes |
|---|---|---|
| MkDocs + Material theme | Replaced | Did not support relationship traversal |
| Obsidian Publish | Evaluated, rejected | Cost; relationship rendering still limited |
| Docusaurus | Considered, rejected | General-purpose; not Obsidian-native; heavy custom work required |
| Quartz v4 | Current (active) | Purpose-built for Obsidian vaults; exposes full content graph at build time; custom TypeScript components can traverse frontmatter relationships; deployed via GitHub Actions → Cloudflare Pages |
Relationship traversal rendering (parent trails, child lists, sibling lists) is not yet implemented in the Quartz build. It is the primary outstanding publishing requirement. See [Content Graph Architecture](Content Graph Architecture.md) for the planned approach.