# 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.