2.7 KiB
ADR 0001 — Step Reference Syntax
Status: Accepted
Context
KitchenMD supports Combined Recipes: files whose sole purpose is to sequence steps from two or more other Recipe Files into a single cooking order (e.g. "penne alla vodka + italian meatballs"). To express this, a Combined Recipe needs to embed specific steps from other files — not entire files or sections, but individual lines of instruction.
Obsidian's existing transclusion syntax (![[file#heading]]) transclude a section from heading to the next heading.
It has no native concept of step-level granularity.
Two approaches were considered:
Option A — Extend Obsidian's anchor syntax with a :N suffix
![[file#section:N]] for a named section, ![[file#N]] for a headingless recipe.
The :N part is a KitchenMD-specific extension; vanilla Obsidian does not recognise it and renders an "unable to find" error for the anchor.
Option B — Use Obsidian block references
Obsidian supports ![[file#^blockid]] to transclude a specific block.
Authors would manually assign block IDs to every step (e.g. ^step-1, ^step-2).
This is valid Obsidian syntax and would render correctly without KitchenMD tooling.
Decision
Option A — extend Obsidian's anchor syntax with :N for section-scoped steps and bare #N for headingless recipes.
Rationale
Option B (block references) requires authors to manually annotate every step with a block ID, which is tedious, error-prone, and pollutes the source file with machine IDs (^step-1) that are meaningless to human readers.
The authoring cost is too high for a format designed to be written naturally.
Option A requires no author effort beyond normal recipe writing. Step numbers are derived automatically by the parser from document structure. The compatibility cost is acceptable: vanilla Obsidian renders a visible "unable to find" error rather than silently corrupting content, so the break is obvious and recoverable. Combined Recipes are a specialised document type — authors who create them are expected to use KitchenMD tooling.
Step numbers are section-local (reset at each heading) rather than global, so adding or removing steps in one section does not renumber steps in other sections and does not break existing Step References elsewhere.
Consequences
- Combined Recipe files will not render correctly in vanilla Obsidian without the KitchenMD plugin; they will show "unable to find" errors for step anchors.
- Individual Recipe Files (non-combined) are unaffected — they contain no Step References and render correctly in vanilla Obsidian.
- The KitchenMD parser and future Obsidian plugin must implement step counting to resolve
![[file#section:N]]and![[file#N]]references.