Progress Note — 2026-02-24

Session with Claude (Sonnet 4.6) covering MkDocs configuration, publishing strategy, and design of a relationship context block.

---

Decisions Made

Publishing target

MkDocs is preferred over Obsidian Publish if cost is the only consideration. The real problem is that neither platform supports Breadcrumbs, Dataview, or Bases natively for published output. The goal is to replicate those capabilities another way.

mkdocs.yml changes made this session

• Added site_url: https://docs.cornillaud.com
• Nav section reviewed; folder structure reorganized with numeric prefixes
• macros plugin identified as unused and risky (Jinja2 conflicts with Obsidian template syntax) — to be removed

room type deprecated

isA: area adds complexity without meaningful benefit for this audience and vault size. All rooms will be reclassified as isA: area. The isIn hierarchy already captures the containment relationship.

• Cleanup task: update existing room notes.

index.md convention

Discussed replacing the folder-note convention (Duplex.md inside Duplex/) with index.md. Benefits: cleaner URLs (/duplex/ vs /duplex/duplex/). Cost: requires updating all wikilinks and the Templater template.

Deferred

After fiddling with this today, I decided not to do this. That does not mean I will never do it, but I certainly won’t do it now, unless there comes to light a compelling argument to do so.

---

Context Block Design (plan on file, implementation deferred)

A “context block” will be auto-injected at the bottom of every qualifying page (isA: area, system, or device) in two environments:

Environment	Mechanism
MkDocs (published)	main.py hook — builds graph at build time, injects block
Obsidian (local)	Dataview inline expressions + DQL query appended to note body

The two are independent; Dataview blocks are stripped by the hook at publish time.

Context block format (published)

---
- isIn: [Root](url) / [Parent](url) / [This Note's Parent](url)
- partOf: [Systems](url) / [Containing System](url)
- dependsOn: [Dependency A](url), [Dependency B](url)
- [Child Note](url) <small>device</small>
  - [Grandchild](url) <small>device</small>...
---

Design decisions

Decision	Choice
Trail direction	Root-first; “this” node excluded
isIn / partOf	Walked upward as a chain (trail mode)
dependsOn	Flat linked list (not a hierarchy, not walked)
Child depth	2; nodes at depth limit with further children get ...
Child type annotation	Always shown: <small>type</small>
Extensibility	RELATIONSHIPS config dict — add new types with one entry, no logic changes
Injection position	Bottom of page (or at a placement marker if one exists — TBD)

Obsidian local block (appended to note body)

	---
	 isIn: `= this.isIn`
	 partOf: `= this.partOf`
	---	
	```dataview
	LIST FROM "" WHERE contains(isIn, this.file.link) OR contains(partOf, this.file.link)
	```

This shows immediate parent (clickable link) and immediate children. Full recursive trail is a publish-only feature (hook has the full graph; Dataview cannot multi-hop).

---

Deferred Ideas

*.ctx.md companion files

For each note NoteTitle.md, a companion NoteTitle.ctx.md could be maintained by a custom Obsidian plugin. The plugin builds/refreshes the context block and writes it into the companion file. The MkDocs hook then renders/inlines the .ctx.md at publish time.

Benefits: clean separation of authoring-time graph traversal from publish-time rendering; source notes stay unmodified. Revisit when ready to build the plugin.

Recursive child hierarchy (separate plan)

The child list in the context block (depth 2) is a first step. A richer standalone “child hierarchy” view — potentially its own page or section — was discussed but not planned. Next planning session.

---

Open To-Do List

#	Task	Status
1	Implement main.py MkDocs hook (plan on file)	Deferred — reviewing
2	Update new-note.md Templater template to append Dataview context block	Pending
3	Write backfill script to append Dataview block to existing qualifying notes	Pending
4	Migrate isA: area notes → isA: area	Pending
5	Remove macros plugin from mkdocs.yml	Pending
6	Plan recursive child hierarchy (separate planning session)	Pending
7	Revisit *.ctx.md companion file concept	Future
8	Revisit index.md folder-note convention	Future

---

Plan File

Full design plan for the main.py hook is saved at: /Users/tim/.claude/plans/dapper-dreaming-river.md

• Why ~/.claude/plans… instead of under .claude in the project folder?