Recipe Edition Design Decisions
===============================

Resolutions for the Phase 1 open decisions listed in
[plan 001][p1], adopting the [edition design criteria][ed] and the
[recipe prompt][pr].  Later phases may revisit any of these as the
edition takes shape.


Ingredient representation
-------------------------

Ingredients are wiki-linked inline within an Ingredients section of
the recipe body.  Example:

    !! Ingredients

    * 1 cup [[flour]]
    * 2 cloves [[garlic]], minced
    * ½ tsp [[salt]]

Ingredient tiddlers are created implicitly by the links.  "Which
recipes use garlic?" is answered by the backlinks of the `garlic`
tiddler.  Quantity stays inline with the name — no separate
quantity or unit fields (unit parsing and conversion are on the
[futures list][p1]).  Relink handles renames across recipes.


Step representation
-------------------

Steps live in a numbered list under a Steps section.  Example:

    !! Steps

    # Preheat the oven to 350°F.
    # Whisk the dry ingredients in a large bowl.
    # …

The recipe body template extracts Ingredients and Steps sections by
heading, and walks the numbered-list items under Steps for the step
navigator.  A recipe that ignores the convention still renders as
plain body text — it simply loses the split layout and step
navigation.


Plugin bundle
-------------

The release HTML build bundles [Relink][rl] and nothing beyond TW
core.  Relink lets users rename ingredient tiddlers and tags
without breaking recipes.

Dev-only plugins (`tiddlywiki/tiddlyweb` and
`tiddlywiki/filesystem`) remain in the Node wiki for editing on
disk but are excluded from the release HTML — they add weight
without value in a single-file build.  `tiddlywiki/highlight` is
dropped entirely; recipes don't need code syntax highlighting.

The mechanism for the dev-vs-release plugin split (separate
`tiddlywiki.info`, build profile, or other) is a Phase 2 detail.


Locale approach
---------------

The edition contains no locale logic.  Templates do not assume a
measurement system or temperature scale; they render whatever the
author wrote.  Localized variation happens through companion
content collections (see [edition design criteria][ed]), not
through code in the edition.

First-pass collections are a US-customary sample and a metric
sample.


Sample-content isolation
------------------------

Every tiddler in a demo collection carries a `demo: yes` *field*.
The original design specified a `$:/community/recipes/demo` tag, but
a field was used instead: a tag would appear in every recipe's tag
bar and in the tag browser, cluttering the user-facing UI.  A field
is invisible to the tag browser and keeps the tag UI clean.

The "Remove Sample Content" affordance filters on
`field:demo[yes]` and lets users remove recipes, ingredients, and
categories selectively before they start.


Addenda
-------

Decisions reached during implementation that extend or revise the
above.


### Reading views ###

The original plan called for three distinct views: a primary reading
view, a side-by-side split view, and a step-by-step view.  These
collapsed into two modes sharing a single recipe-body template:

  - **Normal view** — the body template renders the About block and
    photo above a persistent two-column grid (ingredients left, steps
    right).  Steps render as a plain numbered list — read-only, no
    active-step highlighting and no Previous / Next navigation.  The
    step-by-step affordance lives only in cooking mode, where it
    earns its screen real estate.

  - **Cooking mode** — a toolbar button sets a state tiddler
    (`$:/state/community/recipes/cooking-mode`) to the current recipe
    title, collapsing the sidebar, reducing the story list to just the
    recipe, and hiding metadata, the About section, and all toolbar
    buttons except "Exit cooking mode".  Font size is boosted; steps
    become clickable with the active step visually emphasized; a
    Previous / Next bar fixes to the bottom of the viewport.  On
    phones the ingredients column is hidden by default and can be
    revealed by a toggle in the nav bar.

The mode transition is CSS-driven: the stylesheet includes a
`<$list>` block that emits the cooking-mode rules only when the state
tiddler is non-empty.  No separate tiddler type or route is needed.


### Plugin adoption ###

The initial design named Relink as the sole bundled external plugin.
The build-time policy is broader:

  - Adopt external plugins when they offer a real advantage over a
    custom solution, are actively maintained, and have demonstrated
    community traction.
  - Currently bundled: **Relink** (rename propagation across
    ingredient links) and **AutoComplete** (tiddler-title suggestions
    while authoring, steering users toward canonical ingredient names
    at write time).
  - Evaluated and removed: **uni-link** — evaluated for transparent
    link resolution (`[[garlic]]` → `Garlic`) but does not provide
    it: plain links still navigate to the exact title typed.  The
    aliasing mechanism (see below) handles the mismatch at read time
    instead.


### Photo tiddlers ###

Recipe and ingredient photos are stored as separate tiddlers rather
than embedded in the content tiddler.  The naming convention is
`<ContentTitle> (photo)` — the photo for "Chicken Tikka Masala" is
titled "Chicken Tikka Masala (photo)".  The `photo` field on the
content tiddler holds this title.

A photo tiddler is either:

  - **Embedded** — tiddler body contains base64-encoded image data.
  - **External link** — tiddler has a `_canonical_uri` field with an
    image URL and an empty body.  TiddlyWiki renders both identically.

All sample photo tiddlers carry `photographer` and `photo-source`
attribution fields.  When the source platform differs from the
photographer (e.g., a personal photo hosted on Unsplash), an
optional `photo-source-name` field provides the human-readable
platform name; the recipe and ingredient view templates then render
"Photographer on [Platform](source-url)" beneath the image.  When
the field is absent (e.g., TheMealDB recipe photos where the
photographer credit *is* the source), the caption falls back to
"[Photographer](source-url)".


### Ingredient aliasing ###

Canonical ingredient tiddlers carry an `aliases` field listing
lowercase, plural, and cross-name variants found in recipe bodies
(e.g., `Garlic` has `aliases: garlic`; `Baking Soda` could carry
`aliases: bicarbonate-of-soda`).  When a reader navigates to a
missing tiddler whose title appears in a canonical tiddler's
`aliases` field, the ingredient view template shows
"Alias of [canonical]" and links to it.  The canonical's view also
surfaces an "Also known as" list and merges backlinks from each
alias into its "Recipes using…" panel, so a recipe linking to a
case-variant still appears on the canonical.

Recipe bodies are not edited to fix case-variant links; the alias
mechanism handles the mismatch at read time.

A separate `alias-of` field was considered for redirecting *real*
alias tiddlers (as opposed to missing ones), but dropped — Relink
already handles tiddler renames cleanly, and the `aliases`-only
path covers the remaining read-time aliasing without a second
mechanism.


  [ac]: https://evidentlycube.github.io/TW5-PluginShowcase/#Auto%20Complete
  [ed]: 001-edition-design.md
  [p1]: ../plans/001-recipe-edition.md
  [pr]: ../prompts/002-recipe-edition
  [rl]: https://flibbles.github.io/tw5-relink/
