diff --git a/docs/decisions/ADR-0007-citation-card-format.md b/docs/decisions/ADR-0007-citation-card-format.md new file mode 100644 index 0000000..4c2ae3f --- /dev/null +++ b/docs/decisions/ADR-0007-citation-card-format.md @@ -0,0 +1,115 @@ +# ADR-0007 — Citation card output format (Markdown and HTML) + +- Status: accepted +- Date: 2026-05-25 +- Workplan: CE-WP-0004-T02 (Markdown renderer) and CE-WP-0004-T03 (HTML renderer) +- Spec refs: `wiki/ArchitectureOverview.md` §4.7, §14.1, §14.2, §14.3 + +## Context + +The MVP scenario ends with a user exporting an evidence item as a portable +citation card. Two formats ship in CE-WP-0004: + +- **Markdown** — copied to the clipboard for pasting into notes, emails, + GitHub issues, and so on. Renders well as plain text and as rendered + Markdown. +- **HTML** — copied for pasting into rich-text editors and web pages. + +A third format, the `` Web Component from +`ArchitectureOverview.md` §14.2, is out of scope here and lands in a later +workplan. Its visual presentation should be *equivalent* to the HTML form +but is not constrained to be byte-identical. + +The two formats need a written contract so that: + +1. UI components (T04 sidebar export, future web embeds) can rely on the + exact output structure. +2. Snapshot tests fail loudly if the format drifts. +3. Consumers that style the HTML form know which elements and classes are + stable. + +## Decision + +### Markdown format (CE-WP-0004-T02) + +```markdown +> {quote} + +— *{sourceLabel}* · [Open source]({openContextUrl}) + +{commentary} +``` + +Rules: + +- Each `{quote}` line is rendered with the leading `> ` blockquote marker, + preserving line breaks in the source quote. A single-line quote is one + blockquote line; a multi-line quote becomes multiple `> `-prefixed + lines. +- A blank line follows the blockquote. +- The attribution line uses an em dash (`—`, U+2014) followed by a single + space, the italicised source label, a middle dot (`·`, U+00B7) with + surrounding spaces, and the `[Open source]({openContextUrl})` link. +- The middle dot + link segment is **omitted entirely** when no + `openContextUrl` is provided (which is unusual but possible for + evidence items without an annotation). +- A blank line follows the attribution. +- The optional `{commentary}` paragraph is rendered as-is. When absent + the trailing blank line and commentary paragraph are both omitted. +- The output ends with a single trailing newline. + +Reserved Markdown characters inside the quote are not escaped — the +intent is to reproduce the source text verbatim. The blockquote prefix +already neutralises the most dangerous reflow problems. The +`{sourceLabel}` is escaped to defuse `*`/`_` only; the link target is +URL-encoded by `openContextUrl()`. + +### HTML format (CE-WP-0004-T003) + +A single `