Session with Claude (Sonnet 4.6) covering MkDocs configuration, publishing strategy, and design of a relationship context block.
Decisions Made
Publishing target
Use of MkDocs has been superseded.
Now using Quartz. See 20260227. Any information here related to MkDocs or Publish can be ignored.
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
macrosplugin 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?