45 lines
2.7 KiB
Markdown
45 lines
2.7 KiB
Markdown
# 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.
|