docs: resolve indented code block + tab expansion decision

[jonathanKingston]

Summary

Resolves #9, which asked for a decision between (1) implementing 4-space indented code blocks + tab expansion, or (2) documenting the divergence (optionally behind an indentedCode: false parser option).

The issue was stale. Since it was filed, indented code blocks have already been implemented and now conform: the conformance baseline (summaryBySection in tests/fixtures/commonmark/conformance-baseline.json) records Indented code blocks: 12/12 and Tabs: 6/11. Tokenizing happens in block-tokenizer.ts (indented_code) and emission in renderIndentedCode (render-blocks.ts). So the decision is effectively already made toward option (1) for indented code.

This PR documents that resolved decision and adds a low-risk opt-out option.

What changed

Documentation (the core of the ask) — new Indented code blocks (#9) design invariant in docs/ARCHITECTURE.md:

• Indented code IS supported and conforms (12/12), recognized in the tokenizer and emitted verbatim.
• It is intentionally on by default: LLM output favours fenced code, but as a general-purpose CommonMark library, silently dropping indented code would surprise consumers — hence it stays supported (rationale recorded).
• Tab expansion is partial (6/11): leading-tab → 4-column code indent, tab as ATX-heading separator, and tab-indented continuation lines work; the remaining gaps are the harder tab-column arithmetic cases, tracked by the conformance baseline (a fix shows up as the Tabs count rising on re-baseline). A short note was also added to the README.

Opt-out option (chose to add it — the plumbing was cheap and clean) — renderMarkdown already funneled into renderBlocks via an options object (htmlFromIndent), so exposing the toggle was localized and did not require touching the tokenizer:

• renderMarkdown(md, { indentedCode?: boolean }) — new RenderMarkdownOptions (default true), exported from index.ts.
• Threaded through RenderBlocksOptions.indentedCode (default true) and handled in renderSingleBlock: when false, a top-level indented_code block renders as a prose paragraph instead of <pre><code>. Applied at the top level only — recursive list/blockquote content keeps CommonMark indented-code semantics.

Default behavior is byte-for-byte unchanged, so the conformance baseline is untouched. Added targeted unit tests: { indentedCode: false } renders code as <p>code</p>; default and explicit true still produce <pre><code>.

Verification

• npm run typecheck — clean
• npm test — 378/378 pass (conformance baseline unchanged)
• npm run build — clean

Closes #9

🤖 Generated with Claude Code

https://claude.ai/code/session_01Cv1iyJb9PHMFG3YGp6ffkT

---

Generated by Claude Code