alexion
5841ae5de8
- Add @biomejs/biome 2.5.3 with 2-space indent, double quotes, trailing commas - Add lint and format scripts to root package.json - Update CONTEXT.md: resolve Structured Output shape, add Document AST, Block, Inline Node terms - Add ADR 0002 (remark as internal Markdown parser) - Add ADR 0003 (core defines own AST types) - Add spec: core-parser (Parser implementation and Document AST) - Add spec: cli-view (kitchen view <file> command)
2.2 KiB
ADR 0002 — remark as Core's Internal Markdown Parser
Status: Accepted
Context
@kitchen-md/core must parse CommonMark Markdown (plus Obsidian Flavored Markdown extensions) to build a Document AST.
The spec requires that Annotations follow CommonMark's inline processing rules — they are parsed inside paragraphs and list items, and ignored inside code spans and code blocks.
Correctly detecting those boundaries from scratch requires a complete CommonMark implementation.
Two approaches were considered:
Option A — Use remark/unified
remark is a CommonMark-compliant Markdown parser that produces mdast (a typed Markdown AST).
It has a plugin/transform architecture: OFM extensions (wikilinks, transclusion) are handled by existing community plugins (remark-wiki-link), and KitchenMD annotations are handled by a custom transform plugin that walks mdast text nodes and splits them into annotation nodes.
TypeScript support is first-class.
Option B — Build the Markdown parser from scratch
Write a custom CommonMark parser as part of @kitchen-md/core, with no external Markdown dependency.
Decision
Option A — remark/unified as core's internal Markdown parser.
Rationale
CommonMark is a large, precisely specified standard. Building a correct implementation from scratch is significant work with no unique value to the project — the interesting problems are annotation parsing and document rendering, not Markdown tokenisation.
The "built from scratch" statement in the project spec refers to not forking Cooklang's parser, not to avoiding all external dependencies.
remark's plugin architecture maps cleanly to core's needs: one plugin for OFM wikilinks, one plugin for KitchenMD annotations, both operating as transform passes over an existing mdast.
Consequences
- remark and its plugin ecosystem are build-time dependencies of
@kitchen-md/core. - remark must remain a private implementation detail — its types must not appear in core's public API (see ADR 0003).
- OFM support requires
remark-wiki-link(and the underlyingmicromark-extension-wiki-link/mdast-util-wiki-link). - KitchenMD annotation parsing is implemented as a custom remark transform plugin within core.