Publishing Requirements

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. See also: [To-Do Items](ToDo Items.md) (#22, #23).

---

Core requirement: relationship navigation

The primary unsolved 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.

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

Resolve single vs multiple parents

The dependsOn property in the table above correctly indicates that the object can depend on zero or more objects. Some statements below conflict with that. Fix those

Each relationship is a hierarchy: at most one parent per type per note. The inverse (child) links are maintained by the Breadcrumbs plugin during authoring; the publishing solution must derive them at build time from the upward properties.

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:

1. Trigger automatically on every push to the GitHub repository.
2. Build the static site without manual intervention.
3. Deploy to Cloudflare Pages (current setup) or equivalent CDN.
4. Require no paid hosting beyond what is already in use.

The current GitHub → Cloudflare Pages pipeline via MkDocs meets this requirement and must be preserved or replaced with an equivalent automated pipeline.

---

Rendering compatibility

The publishing solution must render:

• Standard Markdown (headings, lists, tables, code blocks, blockquotes)
• Mermaid diagrams (```mermaid fences)
• Standard Markdown links: [label](path/to/note.md)
• Standard Markdown images: ![](path/to/image.jpg)
• 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:

• Dataview (DQL / DataviewJS) — renders blank on publish; acceptable
• Obsidian Bases (.base files) — Obsidian-native; not published
• Obsidian Canvas (.canvas files) — not published

---

Candidate solutions (as of 2026-02-27)

Solution	Status	Notes
MkDocs + Material theme	Current (active)	Does not support relationship traversal
Obsidian Publish	Evaluated, rejected	Cost; Bases/relationship rendering still limited
Docusaurus	Considered	General-purpose; not Obsidian-native; would require heavy custom work
Quartz v4	Candidate	Purpose-built for Obsidian vaults; exposes full content graph at build time; custom TypeScript components can traverse frontmatter relationships; GitHub Actions + Cloudflare Pages deployment well-supported

See todo #22 for the Quartz investigation task.