From c695b6d024f8c9b2eabface6703ca1910447eea5 Mon Sep 17 00:00:00 2001
From: Jack Hogan <jackhogan4@gmail.com>
Date: Thu, 29 Oct 2026 15:06:40 +0000
Subject: [PATCH 1/3] Merge adjacent definition lists inside containers

Apply the same definition list merging logic that occurs at the top level to blocks within containers.
---
 src/block.rs | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/block.rs b/src/block.rs
index 0864303..d117e74 100644
--- a/src/block.rs
+++ b/src/block.rs
@@ -1599,7 +1599,9 @@ impl<'a> ContainerBuilder<'a> {
             if let Some(block) = self.finish_node(child, close.unwrap_or(child_end), parser) { out.push(Draft { span, block }); }
         }
         Self::bind_ials(&mut out, parser);
-        out
+        let mut merged = Vec::with_capacity(out.len());
+        append_blocks(&mut merged, out); // adjacent definition lists merge inside containers as they do at the top level
+        merged
     }
 
     fn bind_ials(blocks: &mut Vec<Draft>, parser: &mut Parser<'_>) {

From 6fccca8f3c545ccb746c8a3cce261d2e4b9d7a94 Mon Sep 17 00:00:00 2001
From: Jack Hogan <jackhogan4@gmail.com>
Date: Thu, 29 Oct 2026 15:14:03 +0000
Subject: [PATCH 2/3] Unify cross-reference representation

- `XrefSeg` was the scanner's record of a cross-reference item and `Reference` the semantic model's, both built by the same parser from the same grammar.
- `ref_segs` now returns `Reference` items and `XrefSeg` is gone.
- In the Python `inlines()` output a cross-reference item reports `tokens` (`["bare"]` for `-@`) in place of `bare`.
---
 README.md     |  2 +-
 py/src/lib.rs |  4 ++--
 src/ast.rs    |  2 +-
 src/inline.rs | 23 +++++++----------------
 src/lib.rs    |  2 +-
 5 files changed, 12 insertions(+), 21 deletions(-)

diff --git a/README.md b/README.md
index f5f4fa5..ad9435f 100644
--- a/README.md
+++ b/README.md
@@ -482,7 +482,7 @@ Types are `text`, `emph`, `strong`, `strike`, `highlight`, `superscript`, `subsc
 - Code spans include `text`. Raw inlines include `format` and `text`.
 - Math includes `delimiter`, `display`, and `tex`.
 - Attribute groups include `id`.
-- Cross-references include `refs` and `tokens`. Footnote references include `label`. Autolinks include `url`.
+- Cross-references include `refs`, one per item with `target`, `tokens` and `prefix`, and the group's `tokens`. Footnote references include `label`. Autolinks include `url`.
 - Template tokens include `form` (always `inline`), `source`, `syntax`, `body`, `kind`, `name`, and `inverted`. Template tokens inside raw HTML blocks are reported too, at depth 0.
 
 `inlines` accepts the same `math`, `bare_autolinks`, and `templates` options as `md2mdhtml`.
diff --git a/py/src/lib.rs b/py/src/lib.rs
index a52e6ff..9f883a2 100644
--- a/py/src/lib.rs
+++ b/py/src/lib.rs
@@ -291,11 +291,11 @@ fn block_span_node(py: Python<'_>, span: BlockSpan, start: usize, end: usize) ->
 /// `strip_trailing_attr` would consume, as the dialect's own grammar judges it.
 #[pyfunction]
 fn trailing_attr_span(line: &str) -> Option<(usize, usize)> { mdhtml::trailing_attr_span(line) }
-fn xref_refs(py: Python<'_>, refs: Vec<mdhtml::XrefSeg>) -> PyResult<Vec<Py<PyDict>>> {
+fn xref_refs(py: Python<'_>, refs: Vec<mdhtml::Reference>) -> PyResult<Vec<Py<PyDict>>> {
     refs.into_iter().map(|r| {
         let rd = PyDict::new(py);
         rd.set_item("target", r.target)?;
-        rd.set_item("bare", r.bare)?;
+        rd.set_item("tokens", r.tokens)?;
         rd.set_item("prefix", r.prefix)?;
         Ok(rd.unbind())
     }).collect()
diff --git a/src/ast.rs b/src/ast.rs
index e08b233..6994d2a 100644
--- a/src/ast.rs
+++ b/src/ast.rs
@@ -183,7 +183,7 @@ impl Panel {
     }
 }
 
-#[derive(Clone, Debug, PartialEq)]
+#[derive(Clone, Debug, PartialEq, Eq)]
 pub struct Reference { pub target: String, pub tokens: Vec<String>, pub prefix: String }
 
 #[derive(Clone, Debug, PartialEq)]
diff --git a/src/inline.rs b/src/inline.rs
index 1ffd761..cba3757 100644
--- a/src/inline.rs
+++ b/src/inline.rs
@@ -92,7 +92,7 @@ pub enum InlineData {
     Math { delimiter: &'static str, tex: String },
     Raw { format: String, text: String },
     Attrs { id: Option<String> },
-    Xref { refs: Vec<XrefSeg>, tokens: Option<String> },
+    Xref { refs: Vec<crate::ast::Reference>, tokens: Option<String> },
     Template { syntax: String, body: String, kind: crate::template::TokenKind, name: String },
     FootnoteRef { label: String },
     Autolink { url: String },
@@ -219,9 +219,6 @@ fn inline_data(src: &str, ev: &InlineEvent, ctx: &InlineContext<'_>) -> InlineDa
     }
 }
 
-#[derive(Clone, Debug, PartialEq, Eq)]
-pub struct XrefSeg { pub target: String, pub bare: bool, pub prefix: Option<String> }
-
 fn ref_attr(src: &str, at: usize) -> Option<String> {
     trailing_attr(&src[at..]).and_then(|(attr, _)| attr.pairs.iter().find(|(k, _)| k == "ref").map(|(_, v)| v.clone()))
 }
@@ -846,23 +843,17 @@ fn following_link_label_blocks_shortcut(src: &str, after: usize) -> bool {
 }
 
 /// Cross-reference bracket group: `[@id]`, `[-@id]` (bare number), `[Prefix @id]`
-/// (prefix override, single ref only), or `[@a; @b]` groups. Returns the dumb
-/// carrier: a Link with a `data-ref` attr, or a `span[data-refs]` of them for groups.
-fn ref_item(label: &str) -> Option<Inline> {
-    let items = ref_segs(label)?.into_iter().map(|item| crate::ast::Reference { target: item.target,
-            tokens: if item.bare { vec!["bare".into()] } else { Vec::new() }, prefix: item.prefix.unwrap_or_default() }).collect();
-    Some(Inline::Reference { attrs: Attr::default(), items })
-}
+/// (prefix override, single ref only), or `[@a; @b]` groups.
+fn ref_item(label: &str) -> Option<Inline> { Some(Inline::Reference { attrs: Attr::default(), items: ref_segs(label)? }) }
 
-/// The scanner-facing form of the same grammar: parsed segments for a whole
-/// bracket group, or None when the group is not a cross-reference.
-pub fn ref_segs(label: &str) -> Option<Vec<XrefSeg>> {
+/// The items of a bracket group as references, or None when the group is not a cross-reference.
+pub fn ref_segs(label: &str) -> Option<Vec<crate::ast::Reference>> {
     let segs: Vec<&str> = label.split(';').collect();
     let single = segs.len() == 1;
     segs.iter().map(|s| ref_seg_info(s, single)).collect()
 }
 
-fn ref_seg_info(seg: &str, allow_prefix: bool) -> Option<XrefSeg> {
+fn ref_seg_info(seg: &str, allow_prefix: bool) -> Option<crate::ast::Reference> {
     let seg = seg.trim();
     let at = seg.find('@')?;
     let before = &seg[..at];
@@ -875,7 +866,7 @@ fn ref_seg_info(seg: &str, allow_prefix: bool) -> Option<XrefSeg> {
     let mut chars = id.chars();
     let valid_start = chars.next().is_some_and(|c| c.is_ascii_alphanumeric());
     if !valid_start || !chars.all(|c| c.is_ascii_alphanumeric() || c == '-' || c == '_') { return None; }
-    Some(XrefSeg { target: id.to_string(), bare, prefix: (!prefix.is_empty()).then(|| prefix.to_string()) })
+    Some(crate::ast::Reference { target: id.to_string(), tokens: if bare { vec!["bare".into()] } else { Vec::new() }, prefix: prefix.to_string() })
 }
 
 fn code_span(src: &str, i: usize) -> Option<(Inline, usize)> {
diff --git a/src/lib.rs b/src/lib.rs
index c61ad79..cce7473 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -44,7 +44,7 @@ pub use diagnostic::{Diagnostic, Severity};
 #[cfg(feature = "dom")]
 pub use fast5ever;
 pub use highlight::highlight_md;
-pub use inline::{InlineData, InlineNode, XrefSeg};
+pub use inline::{InlineData, InlineNode};
 pub use inline_spans::{SourceNode, source_nodes};
 pub use line::{LineOffset, SourceLocation, SourceSpan};
 #[cfg(feature = "dom")]

From 53941d25f1c5a72bec680d367ae452e79dbd5059 Mon Sep 17 00:00:00 2001
From: Jack Hogan <jackhogan4@gmail.com>
Date: Thu, 29 Oct 2026 15:21:24 +0000
Subject: [PATCH 3/3] Add citations and bibliographies

---
 DEV.md                    |   2 +-
 README.md                 |  10 +-
 docs/DIALECT.md           |  56 ++++++++++-
 docs/sample.html          |  21 ++++
 examples/sample-clean.md  |  16 +++
 examples/sample-render.md |  28 ++++++
 examples/sample.md        |  18 ++++
 py/src/lib.rs             |  55 ++++++++---
 python/mdhtml/export.py   |  12 ++-
 python/mdhtml/md.py       |   9 +-
 python/mdhtml/md2html.py  |   3 +-
 python/mdhtml/typst.py    |  19 +++-
 python/mdhtml/viewmd.py   |   3 +-
 src/ast.rs                |  38 ++++++-
 src/block.rs              |   3 +-
 src/export_html.rs        |   7 +-
 src/html.rs               |  16 +--
 src/import.rs             |   6 +-
 src/inline.rs             |  27 +++--
 src/render.rs             |  43 +++++++-
 src/resolve.rs            | 202 +++++++++++++++++++++++++++++++++-----
 src/tmpl.css              |   3 +
 src/write_md.rs           |  31 +++++-
 tests/canonical.rs        |  32 ++++++
 tests/resolve.rs          |  88 +++++++++++++++--
 tests/test_export.py      |  53 +++++++++-
 tests/test_focused.py     |   4 +-
 27 files changed, 692 insertions(+), 113 deletions(-)

diff --git a/DEV.md b/DEV.md
index 509c82f..7a4ffe8 100644
--- a/DEV.md
+++ b/DEV.md
@@ -53,7 +53,7 @@ The Python binding uses public semantic model, encoder, writer and resolver APIs
 
 ## Shared MDHTML core
 
-`Document` is the shared semantic model. Panels, references and operations have explicit types; table cells, definitions, Figure bodies and operation operands contain blocks. MDHTML is its browser-readable import/encoding boundary. Source drafts, scanner tokens and rewrite traces remain separate from the semantic model. Importers and exporters share the Rust interpretation of raw payloads, metadata, plain text and references.
+`Document` is the shared semantic model. Panels, references, bibliographies and operations have explicit types; table cells, definitions, Figure bodies and operation operands contain blocks. MDHTML is its browser-readable import/encoding boundary. Source drafts, scanner tokens and rewrite traces remain separate from the semantic model. Importers and exporters share the Rust interpretation of raw payloads, metadata, plain text and references.
 
 Public conversion names use `x2y`, with both representations explicit: `md2mdhtml`, `mdhtml2md`, `wiki2mdhtml`, `md2gfm`, `mdhtml2gfm`, `mdhtml2html`, `mdhtml2typst`, `mdhtml2pdf`, external `mdhtml2docx`, `md2dom`, and `mdhtml2dom`. Operations within a representation, including `bake_mdhtml`, `blocks`, `rewrite`, and `fill_md`, keep ordinary verbs.
 
diff --git a/README.md b/README.md
index ad9435f..71078a9 100644
--- a/README.md
+++ b/README.md
@@ -34,7 +34,8 @@ The dialect deviates from CommonMark for three reasons:
 - Panels: `::: callout-note` (also `tip`, `important`, `warning`, `caution`) creates a callout. Add `collapse="true"` or `collapse="false"` for initially closed/open disclosure, or use `::: details` without a callout kind. The first heading is the panel title, not a document heading. These normalize to `div[data-panel]` with an optional `header` title and independent `data-callout` / `data-disclosure` properties. Ordinary divs stay ordinary.
 - Raw passthrough: a Pandoc-style raw attribute names the payload's format. Use exactly `{=name}` as a fenced code block's info string or immediately after inline code. Both forms render as an inert `<script type="application/vnd.mdhtml.raw" data-format="name">`. Payload text stays literal unless it contains an HTML script-data hazard. [The dialect specification](docs/DIALECT.md#converter-specific-raw-data) defines the encoding rule.
 - Template tokens: Jinja, Mustache, or other configured delimiters. Token recognition is opt-in. Tokens become semantic operations in inert HTML template elements. Overlapping opening delimiters use the longest match. Optional balanced scanning handles nested expressions.
-- Cross-references: Quarto-style bracketed references to identified elements. `[@sec-pay]` renders as `<a data-ref href="#sec-pay"></a>`. Each converter resolves the reference for its output format. `[-@sec-pay]` adds the independent `bare` token. `[Clause @sec-pay]` supplies override text. `[@sec-a; @sec-b]` groups references in a `span` marked with `data-refs`. A trailing `{ref=page}` selects the `page` variant. The parser never resolves numbers or checks that targets exist.
+- Cross-references: Quarto-style bracketed references to identified elements. `[@sec-pay]` renders as `<a data-ref href="#sec-pay"></a>`. Each converter resolves the reference for its output format. `[-@sec-pay]` adds the independent `bare` token. `[Clause @sec-pay]` supplies override text, and `[@sec-pay, second sentence]` suffix text. `[@sec-a; @sec-b]` groups references in a `span` marked with `data-refs`. A trailing `{ref=page}` selects the `page` variant. The parser never resolves numbers or checks that targets exist.
+- Citations and bibliographies: a definition list inside `::: {.bibliography}` is the bibliography; each term is a citation label with the citation key as its id. `[@howard2018]` renders as "(Howard and Ruder, 2018)", `[@howard2018]{ref=text}` as "Howard and Ruder (2018)", and `[-@howard2018]` as "(2018)". Items take prefix and suffix text, as in `[see @howard2018, p. 3]`. `cite_style: numeric` in frontmatter, or `cite_style='numeric'` on an exporter, renders "[12]" in bibliography order instead. [The dialect specification](docs/DIALECT.md#citations-and-bibliographies) gives the rules.
 - Table captions and figures: place `: caption {attrs}` immediately after the table's last row, with no blank line. This uses Quarto's caption format but requires the caption to follow the table. The attributes apply to the table. With `implicit_figures=True`, a paragraph containing only one image becomes a Figure with a structured caption and plain-text image alt. The image's id and classes move to the Figure. Both the caption and original alt are retained by MDHTML encoding.
 - Inline footnotes: pandoc-style `^[an inline note]`, numbered together with `[^id]` references.
 
@@ -206,10 +207,10 @@ typst = mdhtml2typst(document)
 
 - Panels have `kind`, `disclosure`, optional `title`, and block `body`.
 - Figures have block `body`, inline `caption`, and `caption_text`. Tables have ordered `head`/`rows`/`foot`, a shared `columns` count, and block-capable cells.
-- Math has `tex`; inline math also has `display`. References have symbolic `items`, each with a target, tokens and optional authored prefix.
+- Math has `tex`; inline math also has `display`. References have symbolic `items`, each with a target, tokens, and optional authored prefix and suffix. Bibliographies have `entries`, each with inline `label`, `label_text`, block `body`, and a `number` in numeric citation style.
 - Operations have `syntax`, `action`, `name`, block-capable `args`, and an optional selected `content` argument index. Their operands are inert unless a renderer explicitly uses them.
 
-`document.bake(...)` returns a new Document with assigned numbers and reference text computed in Rust. It accepts `reftypes`, `number_headings`, `refs` and `links`. `document.index(...)` instead supplies target information and a validated reference `plan` for native live fields. Typst and DOCX use that plan without baking their references.
+`document.bake(...)` returns a new Document with assigned numbers and reference text computed in Rust. It accepts `reftypes`, `number_headings`, `refs`, `links` and `cite_style`. `document.index(...)` instead supplies target information and a validated reference `plan` for native live fields. Typst and DOCX use that plan without baking their references.
 
 `document.mdhtml(callbacks=...)` encodes MDHTML; `document.markdown()` writes canonical md. For GFM, use `document.bake(links=False).markdown(gfm=True, tmpl=...)` or the `mdhtml2gfm` convenience. `document.map_urls(callback)` returns a rewritten Document and leaves operation operands inert. Complete YAML, derived `meta`, and `warnings` remain attached.
 
@@ -482,7 +483,7 @@ Types are `text`, `emph`, `strong`, `strike`, `highlight`, `superscript`, `subsc
 - Code spans include `text`. Raw inlines include `format` and `text`.
 - Math includes `delimiter`, `display`, and `tex`.
 - Attribute groups include `id`.
-- Cross-references include `refs`, one per item with `target`, `tokens` and `prefix`, and the group's `tokens`. Footnote references include `label`. Autolinks include `url`.
+- Cross-references include `refs`, one per item with `target`, `tokens`, `prefix` and `suffix`, and the group's `tokens`. Footnote references include `label`. Autolinks include `url`.
 - Template tokens include `form` (always `inline`), `source`, `syntax`, `body`, `kind`, `name`, and `inverted`. Template tokens inside raw HTML blocks are reported too, at depth 0.
 
 `inlines` accepts the same `math`, `bare_autolinks`, and `templates` options as `md2mdhtml`.
@@ -591,6 +592,7 @@ portable = md2gfm(markdown, number_headings='legal')
 The GFM conversion applies these rules:
 
 - Cross-references become plain text, such as "See Section 1.(a)". They use the same `reftypes`, `number_headings`, and automatic-numbering rules as `mdhtml2html`.
+- Citations become plain text in the document's `cite_style`. Bibliography entries become their bodies, numbered in numeric style.
 - Heading numbers become part of the heading text. Heading attribute lists are removed.
 - Table captions become "Table 1: caption" paragraphs.
 - With `implicit_figures=True`, an image-only paragraph receives a "Figure 1: alt" caption paragraph.
diff --git a/docs/DIALECT.md b/docs/DIALECT.md
index 99d41f6..0e4f2a6 100644
--- a/docs/DIALECT.md
+++ b/docs/DIALECT.md
@@ -373,7 +373,7 @@ See [@sec-payment], [-@tbl-stages], [Clause @sec-late], and
 <span data-refs=""><a href="#sec-payment" data-ref=""></a><a href="#sec-late" data-ref=""></a></span>. Page <a href="#sec-late" data-ref="bare page"></a>.</p>
 ```
 
-References are recognized only inside bracket groups. An id starts with an ASCII letter or digit and continues with ASCII letters, digits, `-`, or `_`. Prefix text requires whitespace before `@` and is allowed only on a lone reference. A reference-only group may contain semicolon-separated references. Explicit link syntax wins, and a group that fails this grammar remains literal text. Thus `[@sec-x](url)` is a link and `[user@host]` is ordinary text.
+References are recognized only inside bracket groups. An id starts with an ASCII letter or digit and continues with ASCII letters, digits, `-`, or `_`. Each item may carry prefix text before `@`, separated from it by whitespace, and suffix text after the id, running to the next `;` or the closing bracket: `[see @sec-late, second sentence; @sec-payment]`. A cross-reference's prefix replaces its prefix word; its suffix follows the resolved text verbatim. A suffix is encoded as the anchor's `data-suffix` attribute. Explicit link syntax wins, and a group that fails this grammar remains literal text. Thus `[@sec-x](url)` is a link and `[user@host]` is ordinary text.
 
 The presence of `data-ref` marks a reference. No token selects the default full rendering. `bare` independently suppresses the prefix word, and at most one of `page`, `text`, `leaf`, or `rel` selects another rendering. Token order is insignificant. Bare `data-ref` and `data-ref=""` are the same DOM value; html5ever serializes it as `data-ref=""`. Unknown or conflicting tokens are MDHTML errors and converters report them as conversion errors. A group uses `data-refs` on its containing `span`.
 
@@ -381,12 +381,61 @@ The `md` `{ref=...}` key is consumed when lowering a reference. On any other ele
 
 The parser does not resolve numbers or require targets to exist. Converters report an unresolved target as a conversion error when their output format supports live references.
 
-Reference targets are id-bearing headings, paragraphs, figures, tables, display-equation blocks, spans and definition terms. Headings resolve to a heading number; figures, tables and equations use independent sequence numbers. Paragraphs support `ref=text` and layout-dependent `ref=page`. Spans and definition terms default to their own text without a prefix; variants requiring numbers are errors. Formats with links link cited text to its definition; GFM emits reference text alone. Page references remain live in Word/Typst; static formats cannot compute a page layout.
+Reference targets are id-bearing headings, paragraphs, figures, tables, display-equation blocks, spans, definition terms and bibliography entries. Headings resolve to a heading number; figures, tables and equations use independent sequence numbers. Paragraphs support `ref=text` and layout-dependent `ref=page`. Spans and definition terms default to their own text without a prefix; variants requiring numbers are errors. A reference to a bibliography entry is a citation and renders by the rules in the citations section below. Formats with links link cited text to its definition; GFM emits reference text alone. Page references remain live in Word/Typst; static formats cannot compute a page layout.
 
 The shipped exporters use Rust's shared reference vocabulary through `mdhtml.export`. `mdhtml2docx` emits REF fields Word keeps live, Typst emits native references, and HTML/GFM consume shared Rust reference baking as links or plain text. Prefix words come from `REFTYPES` (`sec`, `fig`, `tbl`, `eq`; extended per call with `reftypes=`) and heading numbering from `SCHEMES` (`'legal'`, `'decimal'`, or a `{lvlText: numFmt}` dict). Automatic numbering numbers headings exactly when some reference needs a heading number. For HTML, GFM, and Typst, `number_headings=None` inherits the input's metadata setting, falling back to automatic numbering; `False` disables heading numbering, and numeric references to unnumbered headings are errors. Scheme level 0 is the h1 document title, with an empty lvlText: it shows no number, and bumping it restarts every level below, so `%2` is the h2 counter and each document in a file that opens with its own h1 numbers from 1; a title is cited with `{ref=text}`, never by number.
 
 `mdhtml2html` also offers `refs='ids'` for live-preview contexts where targets may sit outside the fragment: each reference bakes as a working link showing its target id (class `xref`), with no registry, numbering, or failure modes - and captions render as authored, since per-fragment numbers would lie. `id_prefix` namespaces the fragment's ids against a host page (the authored id kept in `data-id`), and `fn_salt` adds a further prefix to the `fn-*`/`fnref-*` footnote namespace only, keeping footnote pairs distinct across fragments that share one `id_prefix`.
 
+## Citations and bibliographies
+
+A bibliography is a definition list inside a fenced div with the reserved class `bibliography`. Each term is a citation label, with the citation key as its id. Each definition is the entry as the reader sees it. The list's heading, when there is one, is an ordinary heading outside the div.
+
+`md`:
+
+```markdown
+## References
+
+::: {.bibliography}
+Howard and Ruder, 2018 {#howard2018}
+: Jeremy Howard and Sebastian Ruder. 2018. [Universal Language Model Fine-tuning for Text Classification](https://arxiv.org/abs/1801.06146). In *Proceedings of ACL 2018*.
+
+Merity et al., 2017 {#merity2017}
+: Stephen Merity, Nitish Shirish Keskar, and Richard Socher. 2017. Regularizing and Optimizing LSTM Language Models. *arXiv preprint arXiv:1708.02182*.
+:::
+```
+
+MDHTML:
+
+```html
+<h2>References</h2><div class="bibliography"><dl><dt id="howard2018">Howard and Ruder, 2018</dt><dd>Jeremy Howard and Sebastian Ruder. 2018. <a href="https://arxiv.org/abs/1801.06146">Universal Language Model Fine-tuning for Text Classification</a>. In <em>Proceedings of ACL 2018</em>.</dd><dt id="merity2017">Merity et al., 2017</dt><dd>Stephen Merity, Nitish Shirish Keskar, and Richard Socher. 2017. Regularizing and Optimizing LSTM Language Models. <em>arXiv preprint arXiv:1708.02182</em>.</dd></dl></div>
+```
+
+The `md` importer turns the class into a bibliography in the semantic model, as `callout-*` becomes a panel, and `bibliography` joins the reserved class words. A `bibliography` div whose content is anything other than one definition list stays an ordinary div, and citations to its terms then fail to resolve, which is the diagnostic. A document may contain more than one reference list. Entries keep their authored order, and an entry is listed whether or not anything cites it.
+
+A label has an author part and a year part when it ends with a comma, optional whitespace, and a year: four digits with an optional letter suffix (`2018`, `2018a`). Citations use the label's plain text. "Howard and Ruder, 2018" splits into "Howard and Ruder" and "2018". A label without such an ending, such as "RFC 2616", has no year part and renders identically in every form below.
+
+### Citations
+
+A reference whose target is a bibliography entry is a citation. It uses the bracket grammar and `data-ref` encoding of cross-references. Citations render in one of two styles: frontmatter `cite_style: author-year` (the default) or `cite_style: numeric` sets the document's style, and the exporter's `cite_style` option overrides it, as `number_headings` does. Numeric style numbers entries in document order at bake time.
+
+| `md` | author-year | numeric |
+|:--|:--|:--|
+| `[@howard2018]` | (Howard and Ruder, 2018) | [12] |
+| `[@merity2017; @howard2018]` | (Merity et al., 2017; Howard and Ruder, 2018) | [7, 12] |
+| `[see @howard2018, p. 3]` | (see Howard and Ruder, 2018, p. 3) | see [12, p. 3] |
+| `[-@howard2018]` | (2018) | [12] |
+| `[@howard2018]{ref=text}` | Howard and Ruder (2018) | Howard and Ruder [12] |
+| `[@howard2018, p. 3]{ref=text}` | Howard and Ruder (2018, p. 3) | Howard and Ruder [12, p. 3] |
+| `[-@howard2018]{ref=text}` | 2018 | [12] |
+| `Merity et al. [-@merity2017a; -@merity2017b]` | Merity et al. (2017a; 2017b) | Merity et al. [7, 8] |
+
+The default form is parenthetical, as in Pandoc. The converter supplies the parentheses or brackets, and a group shares one pair. Items are separated by `; `, or by `, ` in a numeric group whose items have no suffix text. `text` selects the in-text form, in which the author part stands outside the parentheses. `bare` (`-@`) suppresses the author part, as Pandoc's `-@` does; on a label with no year part it changes nothing. A suffix renders after the citation text, verbatim, including its leading comma. A prefix renders inside the parentheses in author-year style and before the brackets in numeric style, where the brackets are a marker rather than a remark. Pandoc's in-text spelling, a bare `@key` outside brackets, is not recognised, because an unbracketed `@` must never become a failed reference.
+
+These are errors: `text` on a group or together with a prefix; `page`, `leaf` or `rel` on a citation; and a group that mixes citations with other references.
+
+In author-year style, a converter renders each entry as its body alone; the label is citation data, not list content. In numeric style the entry's number precedes the body. Converters with links link each citation to its entry. GFM emits citation text alone. Typst and DOCX bake citation text too, since Typst's native citations need a bibliography file the document does not have. In `refs='ids'` mode a citation shows its key and the list renders as authored.
+
 ## Raw HTML and md in HTML
 
 Raw HTML participates in the final whole-fragment HTML5 parse. There is no separate balance operation.
@@ -584,6 +633,7 @@ Callbacks are not separately parsed or restricted to the source node's inline/bl
 Beyond the element mapping above, a few structural patterns carry a *meaning* every conforming converter must honor — the in-package `mdhtml2html`, `mdhtml2md`, and `mdhtml2typst` exporters and external `mdhtml2*` packages alike. These rules bind the interpretation, not the medium: each converter renders the meaning as its format best can, and each states its degradation where the format lacks the feature.
 
 - **Cross-references.** An `a` with `data-ref` (or a `span` with `data-refs` grouping several) is a symbolic reference to be resolved and rendered per the captions and cross-references section; a converter never emits the empty carrier unresolved.
+- **Citations.** A reference whose target is a bibliography entry (`div.bibliography > dl > dt[id]`) is a citation, rendered in the document's `cite_style` per the citations section. Entries render as their bodies, numbered in numeric style.
 - **Raw data.** A raw-data `script` carrier addressed to the converter's own format is decoded and spliced; payloads for other formats are dropped (carried opaquely, never rendered as text), per the converter-specific raw data section.
 - **Custom elements** without a native rendering are transparent wrappers: render the children, drop the tag.
 - **Panels.** `div[data-panel]` carries the title/body structure and independent callout/disclosure properties defined above. Titles are labels, not headings. Formats without folding always render the complete body.
@@ -591,7 +641,7 @@ Beyond the element mapping above, a few structural patterns carry a *meaning* ev
 - **Range markers.** Template `section`/`inverted` and `end` operations are paired siblings around the content they control. Converters render unfilled range instructions visibly when appropriate; the content between markers remains normal flow content.
 - **Active-code carriers.** A `text/<lang>-block` script is template code, not content: dropped from final documents by default, echoable as code where an audit register wants it, and never executed by any converter (`instantiate` alone executes).
 
-The class words with assigned converter behavior — `math` for math carriers and `footnotes` on the footnote `section` — are reserved by this section. `details` and `callout-*` are authoring aliases normalized to panels by the `md` importer, not class-based export rules. Other class words are inert data for styling.
+The class words with assigned converter behavior — `math` for math carriers, `footnotes` on the footnote `section` and `bibliography` on a bibliography — are reserved by this section. `details` and `callout-*` are authoring aliases normalized to panels by the `md` importer, not class-based export rules. Other class words are inert data for styling.
 
 ## Warnings
 
diff --git a/docs/sample.html b/docs/sample.html
index 854c9b3..37ad824 100644
--- a/docs/sample.html
+++ b/docs/sample.html
@@ -321,6 +321,27 @@ <h2>Cross-references</h2>
 <h3 id="sec-payment">Payment terms</h3>
 <h4 id="sec-late">Late fees</h4>
 <p>Interest accrues per <a href="#sec-late" data-ref=""></a>, within <a href="#sec-payment" data-ref="bare"></a>, as set out in <a href="#sec-late" data-ref="">Clause</a>. The terms in <span data-refs=""><a href="#sec-payment" data-ref=""></a><a href="#sec-late" data-ref=""></a></span> survive termination. See also <a href="#fig-diagram" data-ref=""></a> and <a href="#tbl-stages" data-ref="bare"></a>, or the mixed pair <span data-refs=""><a href="#fig-diagram" data-ref=""></a><a href="#tbl-stages" data-ref=""></a></span>. Variants: the <a href="#sec-late" data-ref="bare text"></a> clause, on page <a href="#sec-late" data-ref="bare page"></a>, paragraph <a href="#sec-late" data-ref="bare leaf"></a> of <a href="#sec-late" data-ref="bare rel"></a>.</p>
+<h2>Citations and bibliographies</h2>
+<p>A definition list inside <code>::: {.bibliography}</code> is the bibliography: each term is a citation label, and its id is the citation key. <code>[@key]</code> cites in parentheses, <code>{ref=text}</code> cites in running text, and <code>-@</code> drops the author. <code>cite_style: numeric</code> in frontmatter switches to numbered citations:</p>
+<pre><code class="language-markdown">Fine-tuning a pretrained language model [@howard2018] builds on AWD-LSTM [see @merity2017, p. 2]; [@howard2018]{ref=text} report results on six datasets.
+
+::: {.bibliography}
+Howard and Ruder, 2018 {#howard2018}
+: Jeremy Howard and Sebastian Ruder. 2018. Universal Language Model Fine-tuning for Text Classification. In *Proceedings of ACL 2018*.
+
+Merity et al., 2017 {#merity2017}
+: Stephen Merity, Nitish Shirish Keskar, and Richard Socher. 2017. Regularizing and Optimizing LSTM Language Models. *arXiv preprint arXiv:1708.02182*.
+:::
+</code></pre>
+<p>Fine-tuning a pretrained language model <a href="#howard2018" data-ref=""></a> builds on AWD-LSTM <a href="#merity2017" data-ref="" data-suffix=", p. 2">see</a>; <a href="#howard2018" data-ref="text"></a> report results on six datasets.</p>
+<div class="bibliography">
+<dl>
+<dt id="howard2018">Howard and Ruder, 2018</dt>
+<dd>Jeremy Howard and Sebastian Ruder. 2018. Universal Language Model Fine-tuning for Text Classification. In <em>Proceedings of ACL 2018</em>.</dd>
+<dt id="merity2017">Merity et al., 2017</dt>
+<dd>Stephen Merity, Nitish Shirish Keskar, and Richard Socher. 2017. Regularizing and Optimizing LSTM Language Models. <em>arXiv preprint arXiv:1708.02182</em>.</dd>
+</dl>
+</div>
 <h2>Raw passthrough</h2>
 <p>A fenced block whose info string is <code>{=name}</code>, or inline code followed by <code>{=name}</code>, passes through for the converter that understands that format; everyone else drops it:</p>
 <pre><code class="language-markdown">```{=docx}
diff --git a/examples/sample-clean.md b/examples/sample-clean.md
index 3389ef9..9150384 100644
--- a/examples/sample-clean.md
+++ b/examples/sample-clean.md
@@ -255,6 +255,22 @@ See also [@fig-diagram] and [-@tbl-stages], or the mixed pair
 page [-@sec-late]{ref=page}, paragraph [-@sec-late]{ref=leaf} of
 [-@sec-late]{ref=rel}.
 
+## Citations and bibliographies
+
+A definition list inside `::: {.bibliography}` is the bibliography: each term is a citation label,
+and its id is the citation key. `[@key]` cites in parentheses, `{ref=text}` cites in running text,
+and `-@` drops the author. `cite_style: numeric` in frontmatter switches to numbered citations:
+
+Fine-tuning a pretrained language model [@howard2018] builds on AWD-LSTM [see @merity2017, p. 2]; [@howard2018]{ref=text} report results on six datasets.
+
+::: {.bibliography}
+Howard and Ruder, 2018 {#howard2018}
+: Jeremy Howard and Sebastian Ruder. 2018. Universal Language Model Fine-tuning for Text Classification. In *Proceedings of ACL 2018*.
+
+Merity et al., 2017 {#merity2017}
+: Stephen Merity, Nitish Shirish Keskar, and Richard Socher. 2017. Regularizing and Optimizing LSTM Language Models. *arXiv preprint arXiv:1708.02182*.
+:::
+
 ## Raw passthrough
 
 A fenced block whose info string is `{=name}`, or inline code followed by
diff --git a/examples/sample-render.md b/examples/sample-render.md
index edec579..4bac67e 100644
--- a/examples/sample-render.md
+++ b/examples/sample-render.md
@@ -466,6 +466,34 @@ See also [@fig-diagram] and [-@tbl-stages], or the mixed pair
 page [-@sec-late]{ref=page}, paragraph [-@sec-late]{ref=leaf} of
 [-@sec-late]{ref=rel}.
 
+## Citations and bibliographies
+
+A definition list inside `::: {.bibliography}` is the bibliography: each term is a citation label,
+and its id is the citation key. `[@key]` cites in parentheses, `{ref=text}` cites in running text,
+and `-@` drops the author. `cite_style: numeric` in frontmatter switches to numbered citations:
+
+`````markdown
+Fine-tuning a pretrained language model [@howard2018] builds on AWD-LSTM [see @merity2017, p. 2]; [@howard2018]{ref=text} report results on six datasets.
+
+::: {.bibliography}
+Howard and Ruder, 2018 {#howard2018}
+: Jeremy Howard and Sebastian Ruder. 2018. Universal Language Model Fine-tuning for Text Classification. In *Proceedings of ACL 2018*.
+
+Merity et al., 2017 {#merity2017}
+: Stephen Merity, Nitish Shirish Keskar, and Richard Socher. 2017. Regularizing and Optimizing LSTM Language Models. *arXiv preprint arXiv:1708.02182*.
+:::
+`````
+
+Fine-tuning a pretrained language model [@howard2018] builds on AWD-LSTM [see @merity2017, p. 2]; [@howard2018]{ref=text} report results on six datasets.
+
+::: {.bibliography}
+Howard and Ruder, 2018 {#howard2018}
+: Jeremy Howard and Sebastian Ruder. 2018. Universal Language Model Fine-tuning for Text Classification. In *Proceedings of ACL 2018*.
+
+Merity et al., 2017 {#merity2017}
+: Stephen Merity, Nitish Shirish Keskar, and Richard Socher. 2017. Regularizing and Optimizing LSTM Language Models. *arXiv preprint arXiv:1708.02182*.
+:::
+
 ## Raw passthrough
 
 A fenced block whose info string is `{=name}`, or inline code followed by
diff --git a/examples/sample.md b/examples/sample.md
index c2df37a..9fb12fd 100644
--- a/examples/sample.md
+++ b/examples/sample.md
@@ -297,6 +297,24 @@ page [-@sec-late]{ref=page}, paragraph [-@sec-late]{ref=leaf} of
 [-@sec-late]{ref=rel}.
 `````
 
+## Citations and bibliographies
+
+A definition list inside `::: {.bibliography}` is the bibliography: each term is a citation label,
+and its id is the citation key. `[@key]` cites in parentheses, `{ref=text}` cites in running text,
+and `-@` drops the author. `cite_style: numeric` in frontmatter switches to numbered citations:
+
+`````markdown
+Fine-tuning a pretrained language model [@howard2018] builds on AWD-LSTM [see @merity2017, p. 2]; [@howard2018]{ref=text} report results on six datasets.
+
+::: {.bibliography}
+Howard and Ruder, 2018 {#howard2018}
+: Jeremy Howard and Sebastian Ruder. 2018. Universal Language Model Fine-tuning for Text Classification. In *Proceedings of ACL 2018*.
+
+Merity et al., 2017 {#merity2017}
+: Stephen Merity, Nitish Shirish Keskar, and Richard Socher. 2017. Regularizing and Optimizing LSTM Language Models. *arXiv preprint arXiv:1708.02182*.
+:::
+`````
+
 ## Raw passthrough
 
 A fenced block whose info string is `{=name}`, or inline code followed by
diff --git a/py/src/lib.rs b/py/src/lib.rs
index 9f883a2..81b7d47 100644
--- a/py/src/lib.rs
+++ b/py/src/lib.rs
@@ -49,15 +49,19 @@ impl PyDocument {
         doc.map_urls(&mut |url, image| rewrite.call1((url, image))?.extract::<Option<String>>())?;
         Ok(Self { doc })
     }
-    #[pyo3(signature = (reftypes=None, number_headings=None))]
-    fn index(&self, reftypes: Option<HashMap<String, (String, String)>>, number_headings: Option<&Bound<'_, PyAny>>) -> PyResult<PyReferenceIndex> {
-        Ok(PyReferenceIndex { inner: resolve::ReferenceIndex::new(&self.doc, reftypes, parse_number_headings(number_headings)?) })
+    #[pyo3(signature = (reftypes=None, number_headings=None, cite_style=None))]
+    fn index(
+        &self, reftypes: Option<HashMap<String, (String, String)>>, number_headings: Option<&Bound<'_, PyAny>>, cite_style: Option<&str>
+    ) -> PyResult<PyReferenceIndex> {
+        Ok(PyReferenceIndex { inner: resolve::ReferenceIndex::new(&self.doc, reftypes, parse_number_headings(number_headings)?, parse_cite_style(cite_style)?)
+        })
     }
-    #[pyo3(signature = (reftypes=None, number_headings=None, refs="resolve", links=true))]
+    #[pyo3(signature = (reftypes=None, number_headings=None, refs="resolve", links=true, cite_style=None))]
     fn bake(
-        &self, py: Python<'_>, reftypes: Option<HashMap<String, (String, String)>>, number_headings: Option<&Bound<'_, PyAny>>, refs: &str, links: bool
-    ) -> PyResult<Self> {
-        let options = resolve::BakeOptions { reftypes, number_headings: parse_number_headings(number_headings)?, refs: parse_refs(refs)?, links };
+        &self, py: Python<'_>, reftypes: Option<HashMap<String, (String, String)>>, number_headings: Option<&Bound<'_, PyAny>>, refs: &str, links: bool,
+        cite_style: Option<&str>) -> PyResult<Self> {
+        let options = resolve::BakeOptions { reftypes, number_headings: parse_number_headings(number_headings)?, refs: parse_refs(refs)?, links,
+            cite_style: parse_cite_style(cite_style)? };
         let mut doc = self.doc.clone();
         let warnings = py.detach(|| resolve::bake_document(&mut doc, &options)).map_err(vr)?;
         doc.diagnostics.extend(warnings.into_iter().map(|w| mdhtml::Diagnostic::warning("reference", w)));
@@ -141,11 +145,23 @@ impl PyReferenceIndex {
             Ok(d.unbind())
         }).collect()
     }
+    #[getter]
+    fn cite_style(&self) -> &'static str {
+        match self.inner.cite_style { resolve::CiteStyle::AuthorYear => "author-year", resolve::CiteStyle::Numeric => "numeric" }
+    }
+    /// A reference group resolved to inline nodes in `resolve` mode: plain text, or links with `links=True`.
+    #[pyo3(signature = (items, links=false))]
+    fn resolve(&self, py: Python<'_>, items: Vec<Bound<'_, PyDict>>, links: bool) -> PyResult<Vec<Py<PyDict>>> {
+        let items = items.iter().map(reference_from_py).collect::<PyResult<Vec<_>>>()?;
+        let (inlines, _) = self.inner.resolve(&items, resolve::RefsMode::Resolve, links).map_err(vr)?;
+        inline_nodes(py, &inlines)
+    }
 }
 
 fn reference_from_py(node: &Bound<'_, PyDict>) -> PyResult<mdhtml::Reference> {
     let get = |key| node.get_item(key)?.ok_or_else(|| PyKeyError::new_err(key));
-    Ok(mdhtml::Reference { target: get("target")?.extract()?, tokens: get("tokens")?.extract()?, prefix: get("prefix")?.extract()? })
+    let suffix = node.get_item("suffix")?.map(|value| value.extract::<String>()).transpose()?.unwrap_or_default();
+    Ok(mdhtml::Reference { target: get("target")?.extract()?, tokens: get("tokens")?.extract()?, prefix: get("prefix")?.extract()?, suffix })
 }
 
 fn canonical_mdhtml(html: &str) -> String { mdhtml::fast5ever::parse_fragment(html, "body").to_html(mdhtml::fast5ever::DOCUMENT) }
@@ -297,6 +313,7 @@ fn xref_refs(py: Python<'_>, refs: Vec<mdhtml::Reference>) -> PyResult<Vec<Py<Py
         rd.set_item("target", r.target)?;
         rd.set_item("tokens", r.tokens)?;
         rd.set_item("prefix", r.prefix)?;
+        rd.set_item("suffix", r.suffix)?;
         Ok(rd.unbind())
     }).collect()
 }
@@ -602,6 +619,19 @@ fn block_node<'py>(py: Python<'py>, block: &Block) -> PyResult<Bound<'py, PyDict
             d.set_item("items", items)?;
             "definition_list"
         }
+        Block::Bibliography { entries, .. } => {
+            let entries = entries.iter().map(|entry| -> PyResult<Py<PyDict>> {
+                let value = PyDict::new(py);
+                value.set_item("attrs", semantic_attrs(py, Some(&entry.attrs))?)?;
+                value.set_item("label", inline_nodes(py, &entry.label)?)?;
+                value.set_item("label_text", plain(&entry.label))?;
+                value.set_item("body", block_nodes(py, &entry.body)?)?;
+                value.set_item("number", number_node(py, entry.number.as_ref())?)?;
+                Ok(value.unbind())
+            }).collect::<PyResult<Vec<_>>>()?;
+            d.set_item("entries", entries)?;
+            "bibliography"
+        }
         Block::Table { aligns, head, rows, foot, caption, number, .. } => {
             let columns = mdhtml::ast::table_columns(aligns, head, rows, foot);
             d.set_item("columns", columns)?;
@@ -735,6 +765,7 @@ fn reference_node(py: Python<'_>, item: &mdhtml::Reference) -> PyResult<Py<PyDic
     d.set_item("target", &item.target)?;
     d.set_item("tokens", &item.tokens)?;
     d.set_item("prefix", &item.prefix)?;
+    d.set_item("suffix", &item.suffix)?;
     Ok(d.unbind())
 }
 
@@ -773,6 +804,8 @@ fn callback_node<'py>(py: Python<'py>, node: mdhtml::render::EncodeNode<'_>) ->
 // HTML exporter (src/export_html.rs) binding
 // ---------------------------------------------------------------------------
 
+fn parse_cite_style(value: Option<&str>) -> PyResult<Option<resolve::CiteStyle>> { value.map(|name| resolve::CiteStyle::parse(name).map_err(vr)).transpose() }
+
 fn parse_number_headings(value: Option<&Bound<'_, PyAny>>) -> PyResult<Option<resolve::NumberHeadings>> {
     use resolve::NumberHeadings;
     Ok(match value {
@@ -794,11 +827,11 @@ fn parse_refs(refs: &str) -> PyResult<resolve::RefsMode> {
 }
 
 #[pyfunction]
-#[pyo3(signature = (document, reftypes, number_headings, hl, toc, refs, id_prefix, fn_salt, hl_lang, code_wrap, hl_fn, auto_ids, gh_ids))]
+#[pyo3(signature = (document, reftypes, number_headings, hl, toc, refs, id_prefix, fn_salt, hl_lang, code_wrap, hl_fn, auto_ids, gh_ids, cite_style))]
 fn export_html(
     py: Python<'_>, document: &PyDocument, reftypes: Option<HashMap<String, (String, String)>>, number_headings: Option<&Bound<'_, PyAny>>, hl: Option<&str>,
     toc: bool, refs: &str, id_prefix: &str, fn_salt: &str, hl_lang: Option<Py<PyAny>>, code_wrap: Option<Py<PyAny>>, hl_fn: Option<Py<PyAny>>, auto_ids: bool,
-    gh_ids: bool) -> PyResult<(String, Vec<String>)> {
+    gh_ids: bool, cite_style: Option<&str>) -> PyResult<(String, Vec<String>)> {
     use mdhtml::export_html::{HlMode, HtmlExportOptions};
     let number_headings = parse_number_headings(number_headings)?;
     let hook_err: std::sync::Mutex<Option<PyErr>> = std::sync::Mutex::new(None);
@@ -821,7 +854,7 @@ fn export_html(
     let opts = HtmlExportOptions { reftypes, number_headings, hl: match hl {
         None => None, Some("spans") => Some(HlMode::Spans), Some(_) => Some(HlMode::Api)
     }, toc, refs: parse_refs(refs)?, id_prefix: id_prefix.to_string(), fn_salt: fn_salt.to_string(), hl_lang: hl_lang_c.as_ref().map(|c| c as _),
-        code_wrap: code_wrap_c.as_ref().map(|c| c as _), hl_fn: hl_fn_c.as_ref().map(|c| c as _), auto_ids, gh_ids };
+        code_wrap: code_wrap_c.as_ref().map(|c| c as _), hl_fn: hl_fn_c.as_ref().map(|c| c as _), auto_ids, gh_ids, cite_style: parse_cite_style(cite_style)? };
     let result = if hl_lang.is_none() && code_wrap.is_none() && hl_fn.is_none() {
         py.detach(|| mdhtml::export_html::export_document(&document.doc, &opts))
     } else { mdhtml::export_html::export_document(&document.doc, &opts) };
diff --git a/python/mdhtml/export.py b/python/mdhtml/export.py
index 13a29be..a76c21e 100644
--- a/python/mdhtml/export.py
+++ b/python/mdhtml/export.py
@@ -24,10 +24,10 @@ def math_js(fn=None, **opts):
     return _math_js(fn, "".join(f", {k}: {json.dumps(v)}" for k, v in opts.items()))
 
 
-def bake_mdhtml(src, reftypes=None, number_headings=None, refs='resolve', links=True):
+def bake_mdhtml(src, reftypes=None, number_headings=None, refs='resolve', links=True, cite_style=None):
     r"Bake symbolic MDHTML once; links=False emits reference text without anchors. Built-in exporters bake their own input."
     from . import Mdhtml
-    document = import_mdhtml(src).bake(reftypes=reftypes, number_headings=number_headings, refs=refs, links=links)
+    document = import_mdhtml(src).bake(reftypes=reftypes, number_headings=number_headings, refs=refs, links=links, cite_style=cite_style)
     return Mdhtml(document.mdhtml(), document.warnings, document.frontmatter)
 
 
@@ -68,7 +68,8 @@ def go(text, lang):
 
 
 def mdhtml2html(src, dest=None, reftypes: dict | None = None, number_headings=None, hl: str | None = "spans", auto_ids: bool = True,
-    toc: bool = False, refs: str = "resolve", id_prefix: str = "", fn_salt: str = "", hl_lang=None, code_wrap=None, gh_ids: bool = False) -> Html:
+    toc: bool = False, refs: str = "resolve", id_prefix: str = "", fn_salt: str = "", hl_lang=None, code_wrap=None, gh_ids: bool = False,
+    cite_style: str | None = None) -> Html:
     """Lower MDHTML (a string or DocumentFragment; never mutated) to finished HTML: cross-references
     baked as links, headings and captions numbered, `{=html}` raw data spliced, `colwidths` lowered,
     and code highlighted. A `div[data-panel]` with open/closed disclosure lowers to `<details>`,
@@ -97,10 +98,13 @@ def mdhtml2html(src, dest=None, reftypes: dict | None = None, number_headings=No
     without it, code blocks render plain and a warning reports it.
     `number_headings=None` inherits the input's metadata setting, else numbers automatically when
     a reference needs it. `False` disables heading numbering, including automatic numbering.
+    `cite_style` renders citations as author-year text (the default) or as numbers in bibliography order (`'numeric'`);
+    None inherits the input's `cite_style` metadata.
     Returns an `Html` str carrying `.warnings`; `dest` also writes it to a file."""
     document = import_mdhtml(src)
     hl_fn = None if hl is None else _hl_fn(hl)
-    out, warnings = _export_html(document, reftypes, number_headings, hl, toc, refs, id_prefix, fn_salt, hl_lang, code_wrap, hl_fn, auto_ids, gh_ids)
+    out, warnings = _export_html(document, reftypes, number_headings, hl, toc, refs, id_prefix, fn_salt, hl_lang, code_wrap, hl_fn, auto_ids, gh_ids,
+        cite_style)
     res = Html(out, warnings)
     if dest is not None: Path(dest).write_text(res, encoding="utf-8")
     return res
diff --git a/python/mdhtml/md.py b/python/mdhtml/md.py
index 17629f5..28f35f7 100644
--- a/python/mdhtml/md.py
+++ b/python/mdhtml/md.py
@@ -60,14 +60,14 @@ def _extract_img(self, url):
 
 
 def mdhtml2gfm(src, dest=None, reftypes: dict | None = None, number_headings=None, tmpl=None,
-    raw: tuple = ("md", "gfm"), imgdir=None, link=None) -> Md:
+    raw: tuple = ("md", "gfm"), imgdir=None, link=None, cite_style=None) -> Md:
     r"""Export a Document or symbolic MDHTML as GitHub Markdown, with shared Rust numbering and reference text.
 
     `raw` selects passthrough formats; other raw payloads are omitted. `tmpl(node)` renders semantic operations.
     `imgdir` extracts data-URI images. `link(url)` rewrites other URLs. Complete YAML frontmatter is retained.
     """
     document = import_mdhtml(src)
-    prepared = document.bake(reftypes=reftypes, number_headings=number_headings, links=False)
+    prepared = document.bake(reftypes=reftypes, number_headings=number_headings, links=False, cite_style=cite_style)
     if imgdir is not None or link is not None:
         files = _GfmFiles(None if imgdir is None else Path(imgdir), Path(dest).parent if dest is not None else Path("."), link)
         prepared = prepared.map_urls(files.rewrite)
@@ -77,8 +77,9 @@ def mdhtml2gfm(src, dest=None, reftypes: dict | None = None, number_headings=Non
 
 
 def md2gfm(src, dest=None, reftypes: dict | None = None, number_headings=None, math: str = "brackets",
-    implicit_figures: bool = False, templates=None, tmpl=None, raw: tuple = ("md", "gfm"), imgdir=None, link=None) -> Md:
+    implicit_figures: bool = False, templates=None, tmpl=None, raw: tuple = ("md", "gfm"), imgdir=None, link=None, cite_style=None) -> Md:
     "Convert md to GitHub Markdown through the shared MDHTML representation."
     from . import parse_md
     document = parse_md(src, math=math, implicit_figures=implicit_figures, templates=templates)
-    return mdhtml2gfm(document, dest=dest, reftypes=reftypes, number_headings=number_headings, tmpl=tmpl, raw=raw, imgdir=imgdir, link=link)
+    return mdhtml2gfm(document, dest=dest, reftypes=reftypes, number_headings=number_headings, tmpl=tmpl, raw=raw, imgdir=imgdir, link=link,
+        cite_style=cite_style)
diff --git a/python/mdhtml/md2html.py b/python/mdhtml/md2html.py
index 7080def..5c8843d 100644
--- a/python/mdhtml/md2html.py
+++ b/python/mdhtml/md2html.py
@@ -86,6 +86,7 @@ def main(
     fragment: bool = False,  # Emit the body fragment alone, with no page shell
     refs: RefsMode = RefsMode.ids,  # Bake references as target ids, with numbering ('resolve'), or numbering that degrades to ids ('lenient')
     number_headings: NumMode = None,  # Heading numbering scheme (default: the frontmatter's `number_headings:`, else automatic)
+    cite_style: str = None,  # Citation style: 'author-year' or 'numeric' (default: the frontmatter's `cite_style:`, else author-year)
     toc: bool = False,  # Prepend a table of contents
     hl: HlMode = HlMode.spans,  # Code highlighting: classed spans, the Highlight API, or off
     theme: str = "vscode_light",  # Code colors in light mode: any name from `fastpylight.themes()`
@@ -100,7 +101,7 @@ def main(
     "Read Markdown and write a finished HTML page"
     tmpl = dict(templates=MUSTACHE, callbacks={'operation': mustache_pill}) if templates else {}
     src = md2mdhtml(read_src(file), implicit_figures=implicit_figures, frontmatter=frontmatter, **tmpl, **kwargs)
-    html = mdhtml2html(src, auto_ids=auto_ids, gh_ids=gh_ids, refs=refs, number_headings=number_headings, toc=toc,
+    html = mdhtml2html(src, auto_ids=auto_ids, gh_ids=gh_ids, refs=refs, number_headings=number_headings, toc=toc, cite_style=cite_style,
         hl=None if hl == HlMode.off else hl, code_wrap=_code_wrap)
     for w in [*src.warnings, *html.warnings]: print(w, file=sys.stderr)
     if src.meta: html = meta_table(src.meta) + html
diff --git a/python/mdhtml/typst.py b/python/mdhtml/typst.py
index 6603db0..b5dfd1b 100644
--- a/python/mdhtml/typst.py
+++ b/python/mdhtml/typst.py
@@ -63,8 +63,8 @@ def __getnewargs__(self): return (str(self), self.warnings)
 
 
 class _TypstExporter:
-    def __init__(self, document, reftypes, number_headings, tmpl, table_styles=None):
-        self.index = document.index(reftypes=reftypes, number_headings=number_headings)
+    def __init__(self, document, reftypes, number_headings, tmpl, table_styles=None, cite_style=None):
+        self.index = document.index(reftypes=reftypes, number_headings=number_headings, cite_style=cite_style)
         self.targets, self.number_headings = self.index.targets, self.index.number_headings
         self.tmpl, self.fnotes, self.fnotes_done = tmpl, document.footnotes, set()
         self.table_styles = {k.lower(): v for k, v in (table_styles or {}).items()}
@@ -102,6 +102,11 @@ def _block(self, node):
                 terms = [('#metadata(none)' + self._label(t) if t['attrs'].get('id') else '') + self._inline(t['children']) for t in item['terms']]
                 out.extend(f"/ {', '.join(terms)}: {self._blocks(body)}" for body in item['definitions'])
             return '\n'.join(out)
+        if kind == 'bibliography':
+            def entry(e):
+                number = self.targets.get(e['attrs'].get('id'), {}).get('number')
+                return (f"{_esc(number['display'])} " if number else '') + ('#metadata(none)' + self._label(e) if e['attrs'].get('id') else '') + self._blocks(e['body'])
+            return '\n\n'.join(entry(e) for e in node['entries'])
         if kind == 'table': return self._table(node)
         if kind == 'figure': return self._figure(node)
         if kind == 'math_block': return self._math(node, True)
@@ -200,8 +205,10 @@ def _link(self, node):
         return body
 
     def _reference(self, node):
+        parts = self.index.plan(node['items'])
+        if all(part['kind'] == 'citation' for part in parts): return self._inline(self.index.resolve(node['items']))
         out = []
-        for part in self.index.plan(node['items']):
+        for part in parts:
             target, variant, prefix = part['target'], part['variant'], part['prefix']
             if variant != 'page' and (variant == 'text' or part['kind'] in ('text', 'paragraph')):
                 rendered = _esc(prefix) + f"#link(<{target}>)[{_esc(part['text'])}]"
@@ -215,17 +222,19 @@ def _reference(self, node):
         return ''.join(out)
 
 
-def mdhtml2typst(src, dest=None, reftypes: dict | None = None, number_headings=None, tmpl=None, table_styles: dict | None = None, prelude: str = "") -> Typst:
+def mdhtml2typst(src, dest=None, reftypes: dict | None = None, number_headings=None, tmpl=None, table_styles: dict | None = None, prelude: str = "",
+    cite_style: str | None = None) -> Typst:
     r"""Export a Document or symbolic MDHTML as native Typst markup, without modifying the input.
 
     References, numbering, figures, tables and footnotes remain live Typst constructs. LaTeX math uses mitex; `{=typst}` payloads pass through.
     `tmpl(node)` renders semantic operations (`syntax`, `action`, `name`, `args`, `content`, `form`); without it, operations are omitted.
     `number_headings` accepts a scheme name or dict; None uses metadata or automatic numbering for numeric references, and False disables numbering.
+    `cite_style` renders citations as author-year text (the default) or as numbers in bibliography order (`'numeric'`); None uses metadata.
     `table_styles` maps a custom-style name or class, case-insensitively, to Typst table arguments. Custom-style takes priority over classes.
     `prelude` precedes generated setup. The returned Typst string carries warnings; `dest` also writes it to a file.
     """
     document = import_mdhtml(src)
-    ex = _TypstExporter(document, reftypes, number_headings, tmpl, table_styles)
+    ex = _TypstExporter(document, reftypes, number_headings, tmpl, table_styles, cite_style)
     body = ex._blocks(document.blocks)
     parts = [prelude.rstrip()] if prelude else []
     if ex.has_math: parts.append(f'#import "{MITEX}": mi, mitex')
diff --git a/python/mdhtml/viewmd.py b/python/mdhtml/viewmd.py
index 5050682..9264b46 100644
--- a/python/mdhtml/viewmd.py
+++ b/python/mdhtml/viewmd.py
@@ -55,6 +55,7 @@ def main(
     file: str = None,  # Markdown file (or .ipynb notebook) to view (default: stdin)
     refs: RefsMode = RefsMode.lenient,  # References: target ids ('ids'), numbered ('resolve'), or numbered with ids as fallback ('lenient')
     number_headings: NumMode = None,  # Heading numbering scheme (default: the frontmatter's `number_headings:`, else automatic)
+    cite_style: str = None,  # Citation style: 'author-year' or 'numeric' (default: the frontmatter's `cite_style:`, else author-year)
     hl: HlMode = HlMode.spans,  # Code highlighting: classed spans, the Highlight API, or off
     auto_ids: bool = True,  # Derive ids for headings
     implicit_figures: bool = True,  # Promote image-only paragraphs to figures
@@ -69,7 +70,7 @@ def main(
     else: text = read_src(file)
     src = md2mdhtml(text, implicit_figures=implicit_figures, frontmatter=frontmatter,
         templates=MUSTACHE, callbacks={'operation': mustache_pill, 'text': replacements(*DASHES)}, **kwargs)
-    html = mdhtml2html(src, auto_ids=auto_ids, refs=refs, number_headings=number_headings, toc=True,
+    html = mdhtml2html(src, auto_ids=auto_ids, refs=refs, number_headings=number_headings, toc=True, cite_style=cite_style,
         hl=None if hl == HlMode.off else hl, code_wrap=_copy_wrap)
     for w in [*src.warnings, *html.warnings]: print(w)
     base = Path(file).resolve().parent if file else Path.cwd()
diff --git a/src/ast.rs b/src/ast.rs
index 6994d2a..6cc4da1 100644
--- a/src/ast.rs
+++ b/src/ast.rs
@@ -113,6 +113,12 @@ impl Document {
                             for definition in &mut item.definitions { blocks(definition, transform)?; }
                         }
                     }
+                    Block::Bibliography { entries, .. } => {
+                        for entry in entries {
+                            inlines(&mut entry.label, transform)?;
+                            blocks(&mut entry.body, transform)?;
+                        }
+                    }
                     Block::List { items, .. } => { for item in items { blocks(&mut item.blocks, transform)?; } }
                     Block::Element { children, .. } | Block::BlockQuote { children, .. } | Block::Div { children, .. } => blocks(children, transform)?,
                     _ => {}
@@ -184,11 +190,31 @@ impl Panel {
 }
 
 #[derive(Clone, Debug, PartialEq, Eq)]
-pub struct Reference { pub target: String, pub tokens: Vec<String>, pub prefix: String }
+pub struct Reference { pub target: String, pub tokens: Vec<String>, pub prefix: String, pub suffix: String }
 
 #[derive(Clone, Debug, PartialEq)]
 pub struct AssignedNumber { pub display: String, pub reference: String, pub leaf: String }
 
+/// One work in a bibliography: its citation key and label (the term), the
+/// entry as read (the definition), and its number in numeric citation style.
+#[derive(Clone, Debug, PartialEq)]
+pub struct BibliographyEntry { pub attrs: Attr, pub label: Vec<Inline>, pub body: Vec<Block>, pub number: Option<AssignedNumber> }
+
+/// The block for a `bibliography` div: a `Bibliography` when its content is exactly one definition list with one
+/// term per item, else the div as written.
+pub fn bibliography_block(mut attrs: Attr, children: Vec<Block>) -> Block {
+    let entries = match children.as_slice() {
+        [Block::DefinitionList { items, .. }] => items.iter().map(|item| match item.terms.as_slice() {
+            [term] => Some(BibliographyEntry { attrs: term.attrs.clone(), label: term.inlines.clone(), body: item.definitions.concat(), number: None }),
+            _ => None,
+        }).collect::<Option<Vec<_>>>(),
+        _ => None,
+    };
+    match entries {
+        Some(entries) => { attrs.classes.retain(|c| c != "bibliography"); Block::Bibliography { attrs, entries } } None => Block::Div { attrs, children }
+    }
+}
+
 #[derive(Clone, Debug, PartialEq)]
 pub struct ListItem { pub attrs: Attr, pub checked: Option<bool>, pub blocks: Vec<Block> }
 
@@ -238,6 +264,7 @@ pub enum Block {
     BlockQuote { attrs: Attr, children: Vec<Block> },
     List { attrs: Attr, ordered: bool, start: usize, tight: bool, items: Vec<ListItem> },
     DefinitionList { attrs: Attr, items: Vec<DefinitionItem> },
+    Bibliography { attrs: Attr, entries: Vec<BibliographyEntry> },
     CodeBlock { attrs: Attr, lang: Option<String>, text: String },
     Html { raw: String },
     ThematicBreak { attrs: Attr },
@@ -258,8 +285,8 @@ impl Block {
     pub fn attrs(&self) -> Option<&Attr> {
         match self {
             Self::Panel(panel) => Some(&panel.attrs), Self::Paragraph { attrs, .. } | Self::Heading { attrs, .. } | Self::BlockQuote { attrs, .. }
-            | Self::Element { attrs, .. } | Self::List { attrs, .. } | Self::DefinitionList { attrs, .. } | Self::CodeBlock { attrs, .. }
-            | Self::ThematicBreak { attrs } | Self::Table { attrs, .. } | Self::Div { attrs, .. } | Self::Math { attrs, .. }
+            | Self::Element { attrs, .. } | Self::List { attrs, .. } | Self::DefinitionList { attrs, .. } | Self::Bibliography { attrs, .. }
+            | Self::CodeBlock { attrs, .. } | Self::ThematicBreak { attrs } | Self::Table { attrs, .. } | Self::Div { attrs, .. } | Self::Math { attrs, .. }
             | Self::Figure { attrs, .. } => Some(attrs), _ => None
         }
     }
@@ -268,8 +295,9 @@ impl Block {
         match self {
             Self::Panel(panel) => Some(&mut panel.attrs), Self::Element { attrs, .. } => Some(attrs), Self::Paragraph { attrs, .. }
             | Self::Heading { attrs, .. } | Self::BlockQuote { attrs, .. } | Self::List { attrs, .. } | Self::DefinitionList { attrs, .. }
-            | Self::CodeBlock { attrs, .. } | Self::ThematicBreak { attrs } | Self::Table { attrs, .. } | Self::Div { attrs, .. } | Self::Math { attrs, .. }
-            | Self::Figure { attrs, .. } => Some(attrs), Self::Html { .. } | Self::Raw { .. } | Self::Script { .. } | Self::Operation(_) => None
+            | Self::Bibliography { attrs, .. } | Self::CodeBlock { attrs, .. } | Self::ThematicBreak { attrs } | Self::Table { attrs, .. }
+            | Self::Div { attrs, .. } | Self::Math { attrs, .. } | Self::Figure { attrs, .. } => Some(attrs),
+            Self::Html { .. } | Self::Raw { .. } | Self::Script { .. } | Self::Operation(_) => None
         }
     }
 }
diff --git a/src/block.rs b/src/block.rs
index d117e74..acc92e4 100644
--- a/src/block.rs
+++ b/src/block.rs
@@ -309,7 +309,8 @@ fn finalize_block(block: DraftBlock, ctx: &InlineContext<'_>) -> Block {
                 }
                 panel.body = children;
                 Block::Panel(panel)
-            } else { Block::Div { attrs, children } }
+            } else if attrs.classes.iter().any(|c| c == "bibliography") { crate::ast::bibliography_block(attrs, children) }
+            else { Block::Div { attrs, children } }
         }
         DraftBlock::Math { attrs, tex, .. } => Block::Math { attrs, tex, number: None },
         DraftBlock::Footnote { .. } | DraftBlock::HtmlContainer { .. } => unreachable!("footnotes move out and containers splice before finalize_block"),
diff --git a/src/export_html.rs b/src/export_html.rs
index ebfa208..d5ab48b 100644
--- a/src/export_html.rs
+++ b/src/export_html.rs
@@ -5,7 +5,7 @@ use std::collections::{HashMap, HashSet};
 use fast5ever::{DOCUMENT, Dom, NodeId, parse_fragment};
 use unicode_properties::{GeneralCategoryGroup, UnicodeGeneralCategory};
 
-use crate::resolve::{BakeOptions, HEADS, NumberHeadings, RefsMode, bake_document, elements, norm_text};
+use crate::resolve::{BakeOptions, CiteStyle, HEADS, NumberHeadings, RefsMode, bake_document, elements, norm_text};
 
 #[derive(PartialEq, Eq, Clone, Copy)]
 pub enum HlMode { Spans, Api }
@@ -23,7 +23,7 @@ pub type HlHook<'a> = &'a (dyn Fn(&str, &str, HlMode) -> Result<Option<String>,
 pub struct HtmlExportOptions<'a> {
     pub reftypes: Option<HashMap<String, (String, String)>>, pub number_headings: Option<NumberHeadings>, pub hl: Option<HlMode>, pub toc: bool,
     pub refs: RefsMode, pub id_prefix: String, pub fn_salt: String, pub hl_lang: Option<HlLangHook<'a>>, pub code_wrap: Option<CodeWrapHook<'a>>,
-    pub hl_fn: Option<HlHook<'a>>, pub auto_ids: bool, pub gh_ids: bool
+    pub hl_fn: Option<HlHook<'a>>, pub auto_ids: bool, pub gh_ids: bool, pub cite_style: Option<CiteStyle>
 }
 
 /// Lower an MDHTML fragment to finished HTML; returns the markup and the
@@ -35,7 +35,8 @@ pub fn export_document(document: &crate::Document, opts: &HtmlExportOptions) ->
     let mut document = document.clone();
     let mut warnings: Vec<_> = document.diagnostics.iter().map(ToString::to_string).collect();
     warnings.extend(bake_document(
-        &mut document, &BakeOptions { reftypes: opts.reftypes.clone(), number_headings: opts.number_headings.clone(), refs: opts.refs, links: true })?);
+        &mut document, &BakeOptions { reftypes: opts.reftypes.clone(), number_headings: opts.number_headings.clone(), refs: opts.refs, links: true,
+            cite_style: opts.cite_style })?);
     let raw_html = |node: crate::render::EncodeNode<'_>, _: &str| -> Result<Option<String>, String> {
         match node {
             crate::render::EncodeNode::Block(crate::Block::Raw { format, text }) | crate::render::EncodeNode::Inline(crate::Inline::Raw { format, text }) => {
diff --git a/src/html.rs b/src/html.rs
index 7fd6942..24caa5e 100644
--- a/src/html.rs
+++ b/src/html.rs
@@ -15,20 +15,20 @@ impl<'a> Node<'a> {
         let Some(tag) = self.dom.tag(self.id) else { return if matches!(self.dom.get(self.id).data, NodeData::Text { .. }) { "text" } else { "inert" }; };
         match tag {
             "i" => "em", "b" => "strong", "s" => "del", "base" | "link" | "meta" | "style" | "title" => "inert",
-            "div" if self.attr("data-panel").is_some() => "panel", "div" | "span" if self.has_class("math") => "math",
-            "script" if self.attr("type") == Some("application/vnd.mdhtml.raw") => "raw", "script" if self.language().is_some() => "active_code",
-            "script" => "inert", "template" if self.attr("data-op").is_some() => "template", "template" => "inert", "pre" => "code_block",
-            "sup" if self.note().is_some() => "footnote_ref", "a" if self.has_class("footnote-backref") => "inert",
-            "section" if self.has_class("footnotes") => "footnotes", "li" if self.note().is_some() => "footnote",
-            "input" if self.attr("type") == Some("checkbox") => "checkbox", _ => tag
+            "div" if self.attr("data-panel").is_some() => "panel", "div" if self.has_class("bibliography") => "bibliography",
+            "div" | "span" if self.has_class("math") => "math", "script" if self.attr("type") == Some("application/vnd.mdhtml.raw") => "raw",
+            "script" if self.language().is_some() => "active_code", "script" => "inert", "template" if self.attr("data-op").is_some() => "template",
+            "template" => "inert", "pre" => "code_block", "sup" if self.note().is_some() => "footnote_ref",
+            "a" if self.has_class("footnote-backref") => "inert", "section" if self.has_class("footnotes") => "footnotes",
+            "li" if self.note().is_some() => "footnote", "input" if self.attr("type") == Some("checkbox") => "checkbox", _ => tag
         }
     }
     pub fn is_block(self) -> bool {
         match self.kind() {
             "text" | "inert" | "br" | "code" | "img" | "checkbox" | "footnote_ref" => false, "math" => self.dom.tag(self.id) == Some("div"),
             "raw" | "template" => false,
-            "panel" | "code_block" | "active_code" | "footnotes" | "p" | "blockquote" | "hr" | "ul" | "ol" | "pre" | "table" | "figure" | "dl" | "div"
-            | "section" | "details" | "h1" | "h2" | "h3" | "h4" | "h5" | "h6" => true,
+            "panel" | "bibliography" | "code_block" | "active_code" | "footnotes" | "p" | "blockquote" | "hr" | "ul" | "ol" | "pre" | "table" | "figure"
+            | "dl" | "div" | "section" | "details" | "h1" | "h2" | "h3" | "h4" | "h5" | "h6" => true,
             _ => self.dom.tag(self.id).is_some_and(|tag| tag.contains('-')) || self.children().iter().any(|&id| Self::new(self.dom, id).is_block())
         }
     }
diff --git a/src/import.rs b/src/import.rs
index dd473b7..59867d2 100644
--- a/src/import.rs
+++ b/src/import.rs
@@ -109,6 +109,7 @@ impl<'a> Importer<'a> {
                 }
                 Block::DefinitionList { attrs, items }
             }
+            "bibliography" => crate::ast::bibliography_block(attrs, self.blocks(id)),
             "footnotes" => {
                 for item in self.dom.descendants(id) {
                     if self.node(item).kind() != "footnote" { continue; }
@@ -176,7 +177,7 @@ impl<'a> Importer<'a> {
             "code" => Inline::Code { attrs, text: self.dom.to_text(id) },
             "math" => Inline::Math { attrs: self.math_attrs(id), display: self.node(id).display(), tex: self.dom.to_text(id) },
             "a" if self.dom.attr(id, "data-ref").is_some() => {
-                Inline::Reference { attrs: self.attrs(id, &["href", "data-ref"]), items: vec![self.reference(id)] }
+                Inline::Reference { attrs: self.attrs(id, &["href", "data-ref", "data-suffix"]), items: vec![self.reference(id)] }
             }
             "span" if self.dom.attr(id, "data-refs").is_some() => Inline::Reference { attrs: self.attrs(id, &["data-refs"]),
                 items: self.dom.element_children(id).into_iter().map(|id| self.reference(id)).collect() },
@@ -197,7 +198,8 @@ impl<'a> Importer<'a> {
     }
     fn reference(&self, id: NodeId) -> Reference {
         Reference { target: self.dom.attr(id, "href").unwrap_or("#").trim_start_matches('#').into(),
-            tokens: self.dom.attr(id, "data-ref").unwrap_or("").split_whitespace().map(str::to_string).collect(), prefix: self.dom.to_text(id) }
+            tokens: self.dom.attr(id, "data-ref").unwrap_or("").split_whitespace().map(str::to_string).collect(), prefix: self.dom.to_text(id),
+            suffix: self.dom.attr(id, "data-suffix").unwrap_or("").into() }
     }
     fn operation(&mut self, id: NodeId) -> Option<Operation> {
         let (syntax, action) = self.dom.attr(id, "data-op").unwrap().split_once(':').unwrap_or(("", "unknown"));
diff --git a/src/inline.rs b/src/inline.rs
index cba3757..a1625d2 100644
--- a/src/inline.rs
+++ b/src/inline.rs
@@ -842,31 +842,26 @@ fn following_link_label_blocks_shortcut(src: &str, after: usize) -> bool {
     label.is_empty() || valid_link_label(&label, false)
 }
 
-/// Cross-reference bracket group: `[@id]`, `[-@id]` (bare number), `[Prefix @id]`
-/// (prefix override, single ref only), or `[@a; @b]` groups.
+/// Cross-reference bracket group: `[@id]`, `[-@id]` (bare number), `[Prefix @id suffix]`
+/// (prefix and suffix text per item), or `[@a; @b]` groups.
 fn ref_item(label: &str) -> Option<Inline> { Some(Inline::Reference { attrs: Attr::default(), items: ref_segs(label)? }) }
 
 /// The items of a bracket group as references, or None when the group is not a cross-reference.
-pub fn ref_segs(label: &str) -> Option<Vec<crate::ast::Reference>> {
-    let segs: Vec<&str> = label.split(';').collect();
-    let single = segs.len() == 1;
-    segs.iter().map(|s| ref_seg_info(s, single)).collect()
-}
+pub fn ref_segs(label: &str) -> Option<Vec<crate::ast::Reference>> { label.split(';').map(ref_seg_info).collect() }
 
-fn ref_seg_info(seg: &str, allow_prefix: bool) -> Option<crate::ast::Reference> {
+fn ref_seg_info(seg: &str) -> Option<crate::ast::Reference> {
     let seg = seg.trim();
     let at = seg.find('@')?;
     let before = &seg[..at];
     let (before, bare) = match before.strip_suffix('-') { Some(b) => (b, true), None => (before, false) };
     let prefix = before.trim_end();
-    if !prefix.is_empty() && (!allow_prefix || before.len() == prefix.len()) {
-        return None; // prefix text needs trailing whitespace, and only a lone ref takes one
-    }
-    let id = &seg[at + 1..];
-    let mut chars = id.chars();
-    let valid_start = chars.next().is_some_and(|c| c.is_ascii_alphanumeric());
-    if !valid_start || !chars.all(|c| c.is_ascii_alphanumeric() || c == '-' || c == '_') { return None; }
-    Some(crate::ast::Reference { target: id.to_string(), tokens: if bare { vec!["bare".into()] } else { Vec::new() }, prefix: prefix.to_string() })
+    if !prefix.is_empty() && before.len() == prefix.len() { return None; } // prefix text needs trailing whitespace
+    let rest = &seg[at + 1..];
+    let end = rest.find(|c: char| !(c.is_ascii_alphanumeric() || c == '-' || c == '_')).unwrap_or(rest.len());
+    let (id, suffix) = rest.split_at(end);
+    if !id.chars().next().is_some_and(|c| c.is_ascii_alphanumeric()) { return None; }
+    Some(crate::ast::Reference { target: id.to_string(), tokens: if bare { vec!["bare".into()] } else { Vec::new() }, prefix: prefix.to_string(),
+        suffix: suffix.to_string() })
 }
 
 fn code_span(src: &str, i: usize) -> Option<(Inline, usize)> {
diff --git a/src/render.rs b/src/render.rs
index e8a10e6..da8d64a 100644
--- a/src/render.rs
+++ b/src/render.rs
@@ -128,6 +128,21 @@ impl<'a> Renderer<'a> {
                 }
                 out.push_str("</dl>\n");
             }
+            Block::Bibliography { attrs, entries } => {
+                let mut attrs = attrs.clone();
+                attrs.classes.insert(0, "bibliography".into());
+                open_tag("div", &attrs, out);
+                out.push_str("\n<dl>\n");
+                for entry in entries {
+                    if entry.label.is_empty() { open_tag("dd", &entry.attrs, out); } else {
+                        self.inline_element("dt", &entry.attrs, &entry.label, out)?;
+                        out.push_str("\n<dd>");
+                    }
+                    self.content(&entry.body, out, false)?;
+                    out.push_str("</dd>\n");
+                }
+                out.push_str("</dl>\n</div>\n");
+            }
             Block::CodeBlock { attrs, lang, text } => {
                 out.push_str(&code_block_open(attrs, lang.as_deref()));
                 escape_text(text, out);
@@ -302,6 +317,11 @@ impl<'a> Renderer<'a> {
                     out.push_str("\" data-ref=\"");
                     escape_attr(&reference.tokens.join(" "), out);
                     out.push('"');
+                    if !reference.suffix.is_empty() {
+                        out.push_str(" data-suffix=\"");
+                        escape_attr(&reference.suffix, out);
+                        out.push('"');
+                    }
                     if items.len() == 1 { attrs_html(attrs, out); }
                     out.push('>');
                     escape_text(&reference.prefix, out);
@@ -562,12 +582,25 @@ pub(crate) fn plain_with(items: &[Inline], footnote: &dyn Fn(&str) -> String) ->
     let mut out = String::new();
     for item in items {
         match item {
-            Inline::Reference { items, .. } => { for reference in items { out.push_str(&reference.prefix); } }
+            Inline::Reference { items, .. } => {
+                for reference in items {
+                    out.push_str(&reference.prefix);
+                    out.push_str(&reference.suffix);
+                }
+            }
             Inline::Text(text) | Inline::Code { text, .. } | Inline::Math { tex: text, .. } => out.push_str(text),
-            Inline::SoftBreak | Inline::HardBreak => out.push(' '), Inline::Emph { children, .. } | Inline::Strong { children, .. }
-            | Inline::Strike { children, .. } | Inline::Superscript { children, .. } | Inline::Subscript { children, .. } | Inline::Highlight { children, .. }
-            | Inline::Span { children, .. } | Inline::Link { children, .. } | Inline::Element { children, .. } => out.push_str(&plain_with(children, footnote)),
-            Inline::Image { alt, .. } => out.push_str(alt), Inline::FootnoteRef { label } => out.push_str(&footnote(label)),
+            Inline::SoftBreak | Inline::HardBreak => out.push(' '),
+            Inline::Emph { children, .. }
+            | Inline::Strong { children, .. }
+            | Inline::Strike { children, .. }
+            | Inline::Superscript { children, .. }
+            | Inline::Subscript { children, .. }
+            | Inline::Highlight { children, .. }
+            | Inline::Span { children, .. }
+            | Inline::Link { children, .. }
+            | Inline::Element { children, .. } => out.push_str(&plain_with(children, footnote)),
+            Inline::Image { alt, .. } => out.push_str(alt),
+            Inline::FootnoteRef { label } => out.push_str(&footnote(label)),
             Inline::Html(_) | Inline::Operation(_) | Inline::Raw { .. } => {}
         }
     }
diff --git a/src/resolve.rs b/src/resolve.rs
index a611efb..e633c75 100644
--- a/src/resolve.rs
+++ b/src/resolve.rs
@@ -14,21 +14,48 @@ pub enum NumberHeadings { Off, Name(String), Scheme(Vec<(String, String)>) }
 #[derive(PartialEq, Eq, Clone, Copy, Debug, Default)]
 pub enum RefsMode { #[default] Resolve, Ids, Lenient }
 
+/// How citations render: author-year text, or numbers in bibliography order.
+#[derive(PartialEq, Eq, Clone, Copy, Debug, Default)]
+pub enum CiteStyle { #[default] AuthorYear, Numeric }
+
+impl CiteStyle {
+    pub fn parse(name: &str) -> Result<Self, String> {
+        match name {
+            "author-year" => Ok(Self::AuthorYear), "numeric" => Ok(Self::Numeric),
+            other => Err(format!("unknown cite_style {other:?}; use 'author-year' or 'numeric'"))
+        }
+    }
+}
+
 /// Options for numbering document targets and baking reference text.
 pub struct BakeOptions {
-    pub reftypes: Option<HashMap<String, (String, String)>>, pub number_headings: Option<NumberHeadings>, pub refs: RefsMode, pub links: bool
+    pub reftypes: Option<HashMap<String, (String, String)>>, pub number_headings: Option<NumberHeadings>, pub refs: RefsMode, pub links: bool,
+    pub cite_style: Option<CiteStyle>
 }
 
-impl Default for BakeOptions { fn default() -> Self { Self { reftypes: None, number_headings: None, refs: RefsMode::Resolve, links: true } } }
+impl Default for BakeOptions {
+    fn default() -> Self { Self { reftypes: None, number_headings: None, refs: RefsMode::Resolve, links: true, cite_style: None } }
+}
+
+/// The last frontmatter value for `key`.
+fn meta_value(document: &Document, key: &str) -> Option<String> { document.meta().into_iter().rev().find(|(k, _)| k == key).map(|(_, value)| value) }
+
+/// The citation style: explicit, else frontmatter `cite_style`, else author-year.
+fn requested_cite_style(document: &Document, explicit: Option<CiteStyle>) -> Result<CiteStyle, String> {
+    match (explicit, meta_value(document, "cite_style")) {
+        (Some(style), _) => Ok(style), (None, Some(value)) => CiteStyle::parse(&value), (None, None) => Ok(CiteStyle::AuthorYear)
+    }
+}
 
 fn requested_number_headings(document: &Document, explicit: Option<NumberHeadings>) -> Option<NumberHeadings> {
-    explicit.or_else(|| document.meta().into_iter().rev().find(|(key, _)| key == "number_headings").map(|(_, value)| NumberHeadings::Name(value))).map(
-        |option| match option { NumberHeadings::Name(name) if name == "false" => NumberHeadings::Off, option => option })
+    explicit.or_else(|| meta_value(document, "number_headings").map(NumberHeadings::Name)).map(|option| match option {
+        NumberHeadings::Name(name) if name == "false" => NumberHeadings::Off, option => option
+    })
 }
 
 /// Resolve explicit, metadata, and automatic heading numbering for a document.
 pub fn number_headings(document: &Document, explicit: Option<NumberHeadings>) -> Option<NumberHeadings> {
-    ReferenceIndex::new(document, None, explicit).number_headings
+    ReferenceIndex::new(document, None, explicit, None).number_headings
 }
 
 /// The built-in `{lvlText: numFmt}` heading numbering schemes, in level order.
@@ -197,13 +224,13 @@ fn placeholders(lvl_text: &str) -> Vec<u32> {
 }
 
 #[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
-pub enum TargetKind { Heading, Paragraph, Figure, Table, Equation, Text }
+pub enum TargetKind { Heading, Paragraph, Figure, Table, Equation, Citation, Text }
 
 impl TargetKind {
     pub fn as_str(self) -> &'static str {
         match self {
             Self::Heading => "heading", Self::Paragraph => "paragraph", Self::Figure => "figure", Self::Table => "table", Self::Equation => "equation",
-            Self::Text => "text"
+            Self::Citation => "citation", Self::Text => "text"
         }
     }
 
@@ -221,18 +248,24 @@ pub struct ReferencePart<'a> {
 }
 
 #[derive(Clone, Debug)]
-pub struct ReferenceIndex { pub reftypes: HashMap<String, (String, String)>, pub targets: HashMap<String, Target>, pub number_headings: Option<NumberHeadings> }
+pub struct ReferenceIndex {
+    pub reftypes: HashMap<String, (String, String)>, pub targets: HashMap<String, Target>, pub number_headings: Option<NumberHeadings>,
+    pub cite_style: CiteStyle
+}
+
+/// Resolved reference content: the replacement inlines and the export warnings they raised.
+pub type Resolved = (Vec<Inline>, Vec<String>);
 
 impl ReferenceIndex {
     /// Index original semantic targets without assigning numbers or changing the document.
-    pub fn new(document: &Document, reftypes: Option<HashMap<String, (String, String)>>, number_headings: Option<NumberHeadings>) -> Self {
-        Scan::new(document, reftypes, number_headings, true).index
-    }
+    pub fn new(
+        document: &Document, reftypes: Option<HashMap<String, (String, String)>>, number_headings: Option<NumberHeadings>, cite_style: Option<CiteStyle>
+    ) -> Self { Scan::new(document, reftypes, number_headings, true, cite_style).index }
 
     fn empty(extra_reftypes: Option<HashMap<String, (String, String)>>, number_headings: Option<NumberHeadings>) -> Self {
         let mut reftypes = reftypes().into_iter().map(|(key, (single, plural))| (key.into(), (single.into(), plural.into()))).collect::<HashMap<_, _>>();
         if let Some(extra) = extra_reftypes { reftypes.extend(extra); }
-        Self { reftypes, targets: HashMap::new(), number_headings }
+        Self { reftypes, targets: HashMap::new(), number_headings, cite_style: CiteStyle::default() }
     }
 
     fn checked(&self, reference: &Reference) -> Result<(&Target, HashSet<String>), String> {
@@ -245,6 +278,14 @@ impl ReferenceIndex {
         if target.kind == TargetKind::Heading && matches!(self.number_headings, Some(NumberHeadings::Off))
             && matches!(variant.as_str(), "full" | "leaf" | "rel") { return Err(number_error(&reference.target)); }
         if target.kind == TargetKind::Text && !matches!(variant.as_str(), "full" | "text" | "page") { return Err(number_error(&reference.target)); }
+        if target.kind == TargetKind::Citation {
+            if !matches!(variant.as_str(), "full" | "text") {
+                return Err(format!("citation #{} cannot use {{ref={variant}}}; a citation takes {{ref=text}} only", reference.target));
+            }
+            if variant == "text" && !normalized(&reference.prefix).is_empty() {
+                return Err(format!("citation #{} with {{ref=text}} cannot have prefix text", reference.target));
+            }
+        }
         Ok((target, tokens))
     }
 
@@ -254,7 +295,7 @@ impl ReferenceIndex {
     fn prefix_text(&self, reference: &Reference, target: &Target, tokens: &HashSet<String>, plural: bool) -> Result<String, String> {
         let prefix = normalized(&reference.prefix);
         if !prefix.is_empty() { return Ok(format!("{prefix} ")); }
-        if tokens.contains("bare") || ref_variant(tokens) == "text" || matches!(target.kind, TargetKind::Text | TargetKind::Paragraph) {
+        if tokens.contains("bare") || ref_variant(tokens) == "text" || matches!(target.kind, TargetKind::Text | TargetKind::Paragraph | TargetKind::Citation) {
             return Ok(String::new());
         }
         let kind = target.kind.sequence().unwrap_or_else(|| reference.target.split('-').next().unwrap_or(""));
@@ -264,6 +305,7 @@ impl ReferenceIndex {
 
     /// Validate and plan a symbolic reference group without baking its numbers.
     pub fn plan<'a>(&'a self, references: &'a [Reference], mode: RefsMode) -> Result<(Vec<ReferencePart<'a>>, Vec<String>), String> {
+        if mode != RefsMode::Ids { self.citation_group(references)?; }
         let types = references.iter().map(|reference| {
             self.targets.get(&reference.target).and_then(|target| target.kind.sequence()).unwrap_or_else(|| reference.target.split('-').next().unwrap_or(""))
         }).collect::<Vec<_>>();
@@ -288,7 +330,8 @@ impl ReferenceIndex {
     }
 
     /// Resolve one reference group to ordinary semantic text and links.
-    pub fn resolve(&self, references: &[Reference], mode: RefsMode, links: bool) -> Result<(Vec<Inline>, Vec<String>), String> {
+    pub fn resolve(&self, references: &[Reference], mode: RefsMode, links: bool) -> Result<Resolved, String> {
+        if let Some(resolved) = self.citations(references, mode, links)? { return Ok(resolved); }
         let (parts, mut warnings) = self.plan(references, mode)?;
         let mut out = Vec::new();
         for part in parts {
@@ -303,11 +346,7 @@ impl ReferenceIndex {
                 Ok(result) => result, Err(error) if mode == RefsMode::Lenient => { warnings.push(error); None } Err(error) => return Err(error)
             };
             let fallback = resolved.is_none();
-            let (prefix, text) = resolved.map(|text| (part.prefix, text)).unwrap_or_else(|| {
-                let reference = part.reference;
-                let prefix = normalized(&reference.prefix);
-                (String::new(), if prefix.is_empty() { reference.target.clone() } else { format!("{prefix} {}", reference.target) })
-            });
+            let (prefix, text) = resolved.map(|text| (part.prefix, text)).unwrap_or_else(|| (String::new(), fallback_text(part.reference)));
             if links {
                 let text = if references.len() == 1 { format!("{prefix}{text}") } else { if !prefix.is_empty() { out.push(Inline::Text(prefix)); } text };
                 out.push(Inline::Link { attrs: if fallback { Attr::with_class("xref") } else { Attr::default() }, url: format!("#{}", part.reference.target),
@@ -316,6 +355,78 @@ impl ReferenceIndex {
         }
         Ok((out, warnings))
     }
+
+    /// Check a group's citation shape: `Ok(true)` for a group of citations, `Ok(false)` for one that cites no entry.
+    fn citation_group(&self, references: &[Reference]) -> Result<bool, String> {
+        let citations = references.iter().filter(|r| self.targets.get(&r.target).is_some_and(|t| t.kind == TargetKind::Citation)).count();
+        if citations == 0 { return Ok(false); }
+        if citations < references.len() { return Err("a reference group mixes citations with other references".into()); }
+        if references.len() > 1 && references.iter().any(|r| r.tokens.iter().any(|t| t == "text")) {
+            return Err("an in-text citation cites one work; cite several works in one parenthetical group".into());
+        }
+        Ok(true)
+    }
+
+    /// Resolve a citation group in the index's `cite_style`: parenthetical by default, in-text with `text`, author
+    /// suppressed with `bare`. Prefix text sits inside the parentheses in author-year style and before the brackets in
+    /// numeric style. `None` when the group cites no bibliography entry, or in `Ids` mode.
+    fn citations(&self, references: &[Reference], mode: RefsMode, links: bool) -> Result<Option<Resolved>, String> {
+        if mode == RefsMode::Ids || !self.citation_group(references)? { return Ok(None); }
+        let numeric = self.cite_style == CiteStyle::Numeric;
+        let in_text = references.len() == 1 && references[0].tokens.iter().any(|t| t == "text");
+        let plain_group = references.iter().all(|r| r.suffix.is_empty());
+        let (open, close, separator) = if numeric { ("[", "]", if plain_group { ", " } else { "; " }) } else { ("(", ")", "; ") };
+        let mut out = Vec::new();
+        let mut warnings = Vec::new();
+        let lead = normalized(&references[0].prefix);
+        if !in_text {
+            if numeric && !lead.is_empty() { out.push(Inline::Text(format!("{lead} "))); }
+            out.push(Inline::Text(open.into()));
+        }
+        for (i, reference) in references.iter().enumerate() {
+            if i > 0 { out.push(Inline::Text(separator.into())); }
+            let item = self.checked(reference).and_then(|(target, tokens)| {
+                let bare = tokens.contains("bare");
+                let (author, year) = label_parts(&target.text);
+                let number = match (numeric, &target.number) {
+                    (false, _) => None,
+                    (true, Some(number)) => Some(number.leaf.clone()),
+                    (true, None) => {
+                        return Err(format!("citation #{} has no number; numeric style numbers entries when the document is baked", reference.target));
+                    }
+                };
+                let core = match (&number, year) {
+                    (Some(number), _) => number.clone(), (None, Some(year)) if bare => year.to_string(), (None, Some(year)) => format!("{author}, {year}"),
+                    (None, None) => target.text.clone()
+                };
+                Ok((author.to_string(), year.map(str::to_string), core, bare))
+            });
+            let prefix = normalized(&reference.prefix);
+            let suffix = &reference.suffix;
+            let (text, fallback) = match item {
+                Ok((author, year, core, bare)) => {
+                    let text = match (in_text, numeric, year.as_deref(), bare) {
+                        (false, ..) => format!("{}{core}{suffix}", if prefix.is_empty() || numeric && i == 0 { String::new() } else { format!("{prefix} ") }),
+                        (true, true, _, true) => format!("[{core}{suffix}]"), (true, true, _, false) => format!("{author} [{core}{suffix}]"),
+                        (true, false, Some(year), true) => format!("{year}{suffix}"), (true, false, Some(year), false) => format!("{author} ({year}{suffix})"),
+                        (true, false, None, _) => format!("{core}{suffix}")
+                    };
+                    (text, false)
+                }
+                Err(error) if mode == RefsMode::Lenient => {
+                    warnings.push(error);
+                    (if numeric && i == 0 { reference.target.clone() } else { fallback_text(reference) }, true)
+                }
+                Err(error) => return Err(error),
+            };
+            if links {
+                out.push(Inline::Link { attrs: if fallback { Attr::with_class("xref") } else { Attr::default() }, url: format!("#{}", reference.target),
+                    title: None, children: vec![Inline::Text(text)] });
+            } else { out.push(Inline::Text(text)); }
+        }
+        if !in_text { out.push(Inline::Text(close.into())); }
+        Ok(Some((out, warnings)))
+    }
 }
 
 fn number_error(target: &str) -> String {
@@ -324,11 +435,35 @@ fn number_error(target: &str) -> String {
 
 fn normalized(text: &str) -> String { text.split_whitespace().collect::<Vec<_>>().join(" ") }
 
-struct Scan<'a> { index: ReferenceIndex, references: Vec<&'a Reference> }
+/// The text of a reference that cannot resolve: its prefix and target id.
+fn fallback_text(reference: &Reference) -> String {
+    let prefix = normalized(&reference.prefix);
+    if prefix.is_empty() { reference.target.clone() } else { format!("{prefix} {}", reference.target) }
+}
+
+/// An author-year label split at its final comma, `("Dai and Le", Some("2015"))`, when a year (four digits, optional
+/// letter) follows that comma; otherwise the whole label is the author part.
+pub fn label_parts(label: &str) -> (&str, Option<&str>) {
+    let Some((author, year)) = label.rsplit_once(',') else { return (label, None) };
+    let (author, year) = (author.trim_end(), year.trim());
+    let digits = year.as_bytes();
+    let year_like =
+        digits.len() >= 4 && digits[..4].iter().all(u8::is_ascii_digit) && (digits.len() == 4 || digits.len() == 5 && digits[4].is_ascii_lowercase());
+    if year_like && !author.is_empty() { (author, Some(year)) } else { (label, None) }
+}
+
+/// Index targets and references; `entries` counts bibliography entries for index-time numbering in numeric style.
+struct Scan<'a> { index: ReferenceIndex, references: Vec<&'a Reference>, entries: u32 }
+
+/// The number of the `n`th bibliography entry in numeric citation style, shown as `[n]`.
+fn citation_number(n: u32) -> AssignedNumber { AssignedNumber { display: format!("[{n}]"), reference: n.to_string(), leaf: n.to_string() } }
 
 impl<'a> Scan<'a> {
-    fn new(document: &'a Document, reftypes: Option<HashMap<String, (String, String)>>, explicit: Option<NumberHeadings>, auto: bool) -> Self {
-        let mut scan = Self { index: ReferenceIndex::empty(reftypes, requested_number_headings(document, explicit)), references: Vec::new() };
+    fn new(
+        document: &'a Document, reftypes: Option<HashMap<String, (String, String)>>, explicit: Option<NumberHeadings>, auto: bool, cite_style: Option<CiteStyle>
+    ) -> Self {
+        let mut scan = Self { index: ReferenceIndex::empty(reftypes, requested_number_headings(document, explicit)), references: Vec::new(), entries: 0 };
+        scan.index.cite_style = cite_style.unwrap_or_else(|| requested_cite_style(document, None).unwrap_or_default());
         scan.blocks(&document.blocks);
         for note in &document.footnotes { scan.blocks(&note.blocks); }
         if auto && scan.index.number_headings.is_none() && scan.references.iter().any(|reference| {
@@ -382,6 +517,18 @@ impl<'a> Scan<'a> {
                         for definition in &item.definitions { self.blocks(definition); }
                     }
                 }
+                Block::Bibliography { entries, .. } => {
+                    for entry in entries {
+                        let number = entry.number.clone().or_else(|| {
+                            if self.index.cite_style != CiteStyle::Numeric { return None; }
+                            self.entries += 1;
+                            Some(citation_number(self.entries))
+                        });
+                        self.target(&entry.attrs, TargetKind::Citation, crate::plain(&entry.label), number.as_ref());
+                        self.inlines(&entry.label);
+                        self.blocks(&entry.body);
+                    }
+                }
                 Block::Element { children, .. } | Block::BlockQuote { children, .. } | Block::Div { children, .. } => self.blocks(children),
                 Block::List { items, .. } => { for item in items { self.blocks(&item.blocks); } }
                 Block::CodeBlock { .. } | Block::Html { .. } | Block::Raw { .. } | Block::Script { .. } | Block::ThematicBreak { .. } | Block::Operation(_) => {
@@ -414,7 +561,8 @@ impl<'a> Scan<'a> {
 
 /// Assign document numbers and replace symbolic references with ordinary content.
 pub fn bake_document(document: &mut Document, opts: &BakeOptions) -> Result<Vec<String>, String> {
-    let scan = Scan::new(document, opts.reftypes.clone(), opts.number_headings.clone(), opts.refs != RefsMode::Ids);
+    let cite_style = requested_cite_style(document, opts.cite_style)?;
+    let scan = Scan::new(document, opts.reftypes.clone(), opts.number_headings.clone(), opts.refs != RefsMode::Ids, Some(cite_style));
     let mut page_fallback = false;
     for reference in scan.references {
         match scan.index.checked(reference) {
@@ -471,6 +619,13 @@ impl Baker<'_> {
                     let assigned = if attrs.id.is_some() || !caption.is_empty() { self.sequence(TargetKind::Table) } else { None };
                     self.assigned(attrs, number, assigned);
                 }
+                Block::Bibliography { entries, .. } if self.opts.refs != RefsMode::Ids => {
+                    // The index numbered the entries; a baked entry shows its number as its label, or nothing in author-year style.
+                    for entry in entries {
+                        entry.number = entry.attrs.id.as_ref().and_then(|id| self.index.targets.get(id)).and_then(|target| target.number.clone());
+                        entry.label = entry.number.as_ref().map(|number| vec![Inline::Text(number.display.clone())]).unwrap_or_default();
+                    }
+                }
                 Block::Math { attrs, number, .. } => {
                     let assigned = if attrs.id.is_some() { self.sequence(TargetKind::Equation) } else { None };
                     self.assigned(attrs, number, assigned);
@@ -483,6 +638,7 @@ impl Baker<'_> {
                 Block::Figure { body, .. } => self.number_blocks(body),
                 Block::List { items, .. } => { for item in items { self.number_blocks(&mut item.blocks); } }
                 Block::DefinitionList { items, .. } => { for item in items { for definition in &mut item.definitions { self.number_blocks(definition); } } }
+                Block::Bibliography { entries, .. } => { for entry in entries { self.number_blocks(&mut entry.body); } }
                 Block::Table { head, rows, foot, .. } => {
                     for entry in head.iter_mut().chain(rows).chain(foot) {
                         if let TableEntry::Row(row) = entry { for cell in &mut row.cells { self.number_blocks(&mut cell.content); } }
diff --git a/src/tmpl.css b/src/tmpl.css
index 6d3a83d..dd1a6fc 100644
--- a/src/tmpl.css
+++ b/src/tmpl.css
@@ -14,3 +14,6 @@ details > summary { cursor: pointer; font-weight: 600; }
 [data-callout="important"] { --callout-color: #8653b8; }
 [data-callout="warning"] { --callout-color: #a87800; }
 [data-callout="caution"] { --callout-color: #c44040; }
+div.bibliography dl { display: grid; grid-template-columns: max-content 1fr; gap: 0.5em; margin: 1em 0; }
+div.bibliography dl:not(:has(dt)) { grid-template-columns: 1fr; }
+div.bibliography dl > dt, div.bibliography dl > dd { margin: 0; padding: 0; }
diff --git a/src/write_md.rs b/src/write_md.rs
index 2cae949..b762923 100644
--- a/src/write_md.rs
+++ b/src/write_md.rs
@@ -1,4 +1,7 @@
-use crate::ast::{Align, AssignedNumber, Attr, Block, Disclosure, Document, Footnote, Inline, ListItem, Operation, Panel, Reference, TableEntry, TableRow};
+use crate::ast::{
+    Align, AssignedNumber, Attr, Block, DefinitionItem, DefinitionTerm, Disclosure, Document, Footnote, Inline, ListItem, Operation, Panel, Reference,
+    TableEntry, TableRow,
+};
 use crate::render::{EncodeNode, encode_block_with, encode_inlines_with, numbered_tex, panel_attrs};
 use std::fmt::Write;
 use std::ops::Range;
@@ -106,6 +109,26 @@ impl Renderer<'_> {
                 self.ial(attrs, "");
                 self.out.push('\n');
             }
+            Block::Bibliography { attrs, entries } => {
+                if self.options.gfm {
+                    for entry in entries {
+                        self.anchor(&entry.attrs);
+                        if let Some(number) = &entry.number {
+                            self.text(&number.display);
+                            self.out.push(' ');
+                        }
+                        self.blocks(&entry.body)?;
+                    }
+                } else {
+                    let items = entries.iter().map(|entry| DefinitionItem {
+                            terms: vec![DefinitionTerm { attrs: entry.attrs.clone(), inlines: entry.label.clone() }], definitions: vec![entry.body.clone()] })
+                        .collect();
+                    let body = self.capture(|renderer| renderer.block(&Block::DefinitionList { attrs: Attr::default(), items }))?;
+                    let mut attrs = attrs.clone();
+                    attrs.classes.insert(0, "bibliography".into());
+                    fenced_div(&attrs, &body, &mut self.out);
+                }
+            }
             Block::CodeBlock { attrs, lang, text } => {
                 if !self.options.gfm && lang.is_none() && !attrs.classes.is_empty() { return self.html_block(block); }
                 let mut code_attrs = attrs.clone();
@@ -379,8 +402,9 @@ impl Renderer<'_> {
         let Some(first) = items.first() else { return self.html_inline(original); };
         let variants: Vec<_> = first.tokens.iter().filter(|token| token.as_str() != "bare").collect();
         if variants.len() > 1 || variants.iter().any(|token| !matches!(token.as_str(), "page" | "text" | "leaf" | "rel"))
-            || items.iter().any(|item| item.tokens.iter().filter(|token| token.as_str() != "bare").collect::<Vec<_>>() != variants)
-            || items.len() > 1 && items.iter().any(|item| !item.prefix.is_empty()) { return self.html_inline(original); }
+            || items.iter().any(|item| item.tokens.iter().filter(|token| token.as_str() != "bare").collect::<Vec<_>>() != variants) {
+                return self.html_inline(original);
+            }
         self.out.push('[');
         for (i, reference) in items.iter().enumerate() {
             if i > 0 { self.out.push_str("; "); }
@@ -391,6 +415,7 @@ impl Renderer<'_> {
             if reference.tokens.iter().any(|token| token == "bare") { self.out.push('-'); }
             self.out.push('@');
             self.out.push_str(&reference.target);
+            self.out.push_str(&reference.suffix);
         }
         self.out.push(']');
         let mut attrs = attrs.clone();
diff --git a/tests/canonical.rs b/tests/canonical.rs
index 147c45b..0e6a130 100644
--- a/tests/canonical.rs
+++ b/tests/canonical.rs
@@ -1,3 +1,4 @@
+use mdhtml::ast::Block;
 #[cfg(feature = "dom")]
 use mdhtml::export_html::{HlMode, HtmlExportOptions, export_html};
 use mdhtml::{Options, parse, render, render_md};
@@ -181,3 +182,34 @@ decision-making stays plain.
     assert!(canonical.contains("  \\- continuation that looks like a nested list"));
     assert_eq!(render(&parse(&canonical, &options)), render(&document), "canonical Markdown:\n{canonical}");
 }
+
+#[test]
+fn bibliographies_and_reference_suffixes_roundtrip() {
+    let source = r"See [@howard2018], [see @howard2018, p. 33; @merity2017], and [-@howard2018]{ref=text}.
+
+## References
+
+::: {.bibliography}
+Howard and Ruder, 2018 {#howard2018}
+: Jeremy Howard and Sebastian Ruder. 2018. *Universal Language Model Fine-tuning for Text Classification*.
+
+Merity et al., 2017 {#merity2017}
+: Stephen Merity, Nitish Shirish Keskar, and Richard Socher. 2017. Regularizing and Optimizing LSTM Language Models.
+:::
+
+::: {.bibliography}
+Not a list.
+:::
+";
+    let options = Options::default();
+    let document = parse(source, &options);
+    assert!(document.diagnostics.is_empty());
+    let kinds: Vec<_> = document.blocks.iter().map(|block| matches!(block, Block::Bibliography { .. })).collect();
+    assert_eq!(kinds, [false, false, true, false], "a bibliography div without one definition list stays a div");
+    let html = render(&document);
+    assert!(html.contains(r#"<div class="bibliography">"#) && html.contains(r#"<dt id="howard2018">Howard and Ruder, 2018</dt>"#), "{html}");
+    assert!(html.contains(r##"<a href="#howard2018" data-ref="" data-suffix=", p. 33">see</a>"##), "{html}");
+    let canonical = render_md(&document);
+    assert!(canonical.contains("[see @howard2018, p. 33; @merity2017]") && canonical.contains("::: {.bibliography}"), "{canonical}");
+    assert_eq!(parse(&canonical, &options).blocks, document.blocks, "{canonical}");
+}
diff --git a/tests/resolve.rs b/tests/resolve.rs
index 7e03d80..87a4bcf 100644
--- a/tests/resolve.rs
+++ b/tests/resolve.rs
@@ -1,5 +1,5 @@
 use mdhtml::ast::{Block, Document, Operation, OperationArg, Reference, TableEntry};
-use mdhtml::resolve::{BakeOptions, NumberHeadings, ReferenceIndex, RefsMode, TargetKind, bake_document};
+use mdhtml::resolve::{BakeOptions, CiteStyle, NumberHeadings, ReferenceIndex, RefsMode, TargetKind, bake_document};
 use std::collections::HashMap;
 
 fn cited(document: &Document) -> String {
@@ -9,7 +9,7 @@ fn cited(document: &Document) -> String {
 }
 
 fn reference(target: &str, tokens: &[&str]) -> Reference {
-    Reference { target: target.into(), tokens: tokens.iter().map(|value| (*value).into()).collect(), prefix: String::new() }
+    Reference { target: target.into(), tokens: tokens.iter().map(|value| (*value).into()).collect(), prefix: String::new(), suffix: String::new() }
 }
 
 #[test]
@@ -65,7 +65,7 @@ flowchart LR
     };
     let mut linked = document.clone();
     assert!(bake_document(&mut linked, &options).unwrap().is_empty());
-    let index = ReferenceIndex::new(&linked, None, None);
+    let index = ReferenceIndex::new(&linked, None, None, None);
     assert_eq!(index.targets["sec-b"].kind, TargetKind::Heading);
     assert_eq!(index.targets["p-refs"].kind, TargetKind::Paragraph);
     assert_eq!(index.targets["def-term"].kind, TargetKind::Text);
@@ -106,7 +106,7 @@ flowchart LR
 fn reference_modes_control_validation_and_automatic_numbering() {
     let source = "## First {#sec-a}\n\n[@sec-a], [Missing @sec-missing].\n{: #p-refs}";
     let document = mdhtml::parse(source, &Default::default());
-    assert!(matches!(ReferenceIndex::new(&document, None, None).number_headings, Some(NumberHeadings::Name(name)) if name == "decimal"));
+    assert!(matches!(ReferenceIndex::new(&document, None, None, None).number_headings, Some(NumberHeadings::Name(name)) if name == "decimal"));
     assert!(bake_document(&mut document.clone(), &BakeOptions::default()).unwrap_err().contains("not found"));
     let mut lenient = document.clone();
     let warnings = bake_document(&mut lenient, &BakeOptions { refs: RefsMode::Lenient, links: false, ..Default::default() }).unwrap();
@@ -115,15 +115,15 @@ fn reference_modes_control_validation_and_automatic_numbering() {
     let mut ids = document;
     assert!(bake_document(&mut ids, &BakeOptions { refs: RefsMode::Ids, ..Default::default() }).unwrap().is_empty());
     assert_eq!(cited(&ids), "sec-a, Missing sec-missing.");
-    assert!(ReferenceIndex::new(&ids, None, None).targets["sec-a"].number.is_none());
+    assert!(ReferenceIndex::new(&ids, None, None, None).targets["sec-a"].number.is_none());
     let off = mdhtml::parse("---\nnumber_headings: false\n---\n\n## First {#sec-a}\n\n[@sec-a]", &Default::default());
     assert!(bake_document(&mut off.clone(), &BakeOptions::default()).unwrap_err().contains("needs a number"));
-    let index = ReferenceIndex::new(&off, None, None);
+    let index = ReferenceIndex::new(&off, None, None, None);
     assert!(index.validate(&reference("sec-a", &["page"])).is_ok());
     assert!(index.validate(&reference("sec-a", &[])).is_err());
-    assert!(matches!(ReferenceIndex::new(&off, None, Some(NumberHeadings::Name("false".into()))).number_headings, Some(NumberHeadings::Off)));
+    assert!(matches!(ReferenceIndex::new(&off, None, Some(NumberHeadings::Name("false".into())), None).number_headings, Some(NumberHeadings::Off)));
     let page = mdhtml::parse("## First {#sec-a}\n\n[-@sec-a]{ref=page}", &Default::default());
-    assert!(ReferenceIndex::new(&page, None, None).number_headings.is_none());
+    assert!(ReferenceIndex::new(&page, None, None, None).number_headings.is_none());
     let mut overridden = off;
     assert!(
         bake_document(&mut overridden, &BakeOptions { number_headings: Some(NumberHeadings::Name("decimal".into())), ..Default::default() })
@@ -162,7 +162,7 @@ See [@eq-energy], [-@force-label], [@eq-energy; @force-label], and [@eq-list].
     assert!(document.diagnostics.is_empty(), "{:?}", document.diagnostics);
     let mut baked = document.clone();
     assert!(bake_document(&mut baked, &BakeOptions { links: false, ..Default::default() }).unwrap().is_empty());
-    let index = ReferenceIndex::new(&baked, None, None);
+    let index = ReferenceIndex::new(&baked, None, None, None);
     for (id, number) in [("eq-energy", "1"), ("force-label", "2"), ("eq-list", "3")] {
         assert_eq!(index.targets[id].kind, TargetKind::Equation);
         assert_eq!(index.targets[id].number.as_ref().unwrap().display, number);
@@ -173,5 +173,73 @@ See [@eq-energy], [-@force-label], [@eq-energy; @force-label], and [@eq-list].
     assert_eq!(cited(&baked), "See Equation 1, 2, Equations 1 and 2, and Equation 3.");
     let mut ids = document;
     assert!(bake_document(&mut ids, &BakeOptions { refs: RefsMode::Ids, ..Default::default() }).unwrap().is_empty());
-    assert!(ReferenceIndex::new(&ids, None, None).targets["eq-energy"].number.is_none());
+    assert!(ReferenceIndex::new(&ids, None, None, None).targets["eq-energy"].number.is_none());
+}
+
+#[test]
+fn citations_render_in_both_styles() {
+    let source = r"See [@howard2018], [see @howard2018, p. 33; @merity2017], [@howard2018]{ref=text}, [-@howard2018], [-@howard2018]{ref=text}, [@howard2018, p. 33]{ref=text}, and [@rfc2616].
+{: #p-refs}
+
+::: {.bibliography}
+Howard and Ruder, 2018 {#howard2018}
+: Howard entry.
+
+Merity et al., 2017 {#merity2017}
+: Merity entry.
+
+RFC 2616 {#rfc2616}
+: Fielding entry.
+:::
+";
+    let document = mdhtml::parse(source, &Default::default());
+    assert!(document.diagnostics.is_empty(), "{:?}", document.diagnostics);
+    let entries = |document: &Document| {
+        document.blocks.iter().find_map(|block| match block {
+            Block::Bibliography { entries, .. } => Some(entries.iter().map(|entry| entry.number.as_ref().map(|n| n.display.clone())).collect::<Vec<_>>()),
+            _ => None,
+        }).unwrap()
+    };
+    let mut baked = document.clone();
+    assert!(bake_document(&mut baked, &BakeOptions { links: false, ..Default::default() }).unwrap().is_empty());
+    assert_eq!(
+        cited(&baked),
+        "See (Howard and Ruder, 2018), (see Howard and Ruder, 2018, p. 33; Merity et al., 2017), Howard and Ruder (2018), (2018), 2018, Howard and Ruder (2018, p. 33), and (RFC 2616)."
+    );
+    assert_eq!(entries(&baked), [None, None, None]);
+    let index = ReferenceIndex::new(&document, None, None, None);
+    assert_eq!(index.targets["howard2018"].kind, TargetKind::Citation);
+    assert_eq!(index.targets["howard2018"].text, "Howard and Ruder, 2018");
+    let mut numeric = document.clone();
+    let options = BakeOptions { links: false, cite_style: Some(CiteStyle::Numeric), ..Default::default() };
+    assert!(bake_document(&mut numeric, &options).unwrap().is_empty());
+    assert_eq!(cited(&numeric), "See [1], see [1, p. 33; 2], Howard and Ruder [1], [1], [1], Howard and Ruder [1, p. 33], and [3].");
+    assert_eq!(entries(&numeric), [Some("[1]".into()), Some("[2]".into()), Some("[3]".into())]);
+    assert_eq!(
+        cited(&{
+            let mut d = mdhtml::parse("[@a; @b]\n{: #p-refs}\n\n::: {.bibliography}\nA, 2001 {#a}\n: x\n\nB, 2002 {#b}\n: y\n:::", &Default::default());
+            bake_document(&mut d, &options).unwrap();
+            d
+        }), "[1, 2]"
+    );
+    let with_frontmatter = mdhtml::parse(&format!("---\ncite_style: numeric\n---\n\n{source}"), &Default::default());
+    assert_eq!(ReferenceIndex::new(&with_frontmatter, None, None, None).targets["merity2017"].number.as_ref().unwrap().display, "[2]");
+    assert_eq!(ReferenceIndex::new(&document, None, None, Some(CiteStyle::Numeric)).targets["merity2017"].number.as_ref().unwrap().display, "[2]");
+    let mut overridden = with_frontmatter.clone();
+    bake_document(&mut overridden, &BakeOptions { links: false, cite_style: Some(CiteStyle::AuthorYear), ..Default::default() }).unwrap();
+    assert!(cited(&overridden).starts_with("See (Howard and Ruder, 2018)"));
+    let bibliography = &source[source.find(":::").unwrap()..];
+    for (bad, message) in [
+        ("[@howard2018]{ref=page}", "ref=page"), ("[see @howard2018]{ref=text}", "prefix"), ("[@howard2018; @merity2017]{ref=text}", "one work"),
+        ("[@howard2018; @sec-a]", "mixes"),
+    ] {
+        let mut doc = mdhtml::parse(&format!("## A {{#sec-a}}\n\n{bad}\n\n{bibliography}"), &Default::default());
+        let error = bake_document(&mut doc, &BakeOptions::default()).unwrap_err();
+        assert!(error.contains(message), "{bad}: {error}");
+    }
+    let mut bad_style = mdhtml::parse("---\ncite_style: harvard\n---\n\ntext", &Default::default());
+    assert!(bake_document(&mut bad_style, &BakeOptions::default()).unwrap_err().contains("cite_style"));
+    let mut ids = document;
+    bake_document(&mut ids, &BakeOptions { refs: RefsMode::Ids, links: false, ..Default::default() }).unwrap();
+    assert!(cited(&ids).starts_with("See howard2018, see howard2018"), "{}", cited(&ids));
 }
diff --git a/tests/test_export.py b/tests/test_export.py
index 78d64f1..6e0087e 100644
--- a/tests/test_export.py
+++ b/tests/test_export.py
@@ -2,7 +2,7 @@
 
 import pytest
 
-from mdhtml import mdhtml2dom, mdhtml2html, mdhtml2typst, mdhtml2gfm, md2gfm, md2mdhtml
+from mdhtml import mdhtml2dom, mdhtml2html, mdhtml2md, mdhtml2typst, mdhtml2gfm, md2gfm, md2mdhtml, parse_md
 from mdhtml.mustache import MUSTACHE, mustache_code
 from helpers import PNG_B64, normalize_html
 
@@ -540,3 +540,54 @@ def test_equation_exports():
     assert 'a = 1\n\\tag{1}' in html and 'b = 2\n\\tag{2}' in html and 'c = 3\n\\tag{3}' in html
     assert '$$\nx = y\n$$' in gfm and '> b = 2\n> \\tag{2}\n> $$' in gfm and '  c = 3\n  \\tag{3}\n  $$' in gfm
     assert 'See Equation 1, 2, and Equations 2 and 3.' in gfm and '[@' not in gfm
+
+
+CITATIONS = r"""---
+cite_style: numeric
+---
+
+See [@howard2018], [see @howard2018, p. 33; @merity2017], [@howard2018]{ref=text}, and [-@howard2018].
+
+## References
+
+::: {.bibliography}
+Howard and Ruder, 2018 {#howard2018}
+: Jeremy Howard and Sebastian Ruder. 2018. *Universal Language Model Fine-tuning for Text Classification*.
+
+Merity et al., 2017 {#merity2017}
+: Stephen Merity, Nitish Shirish Keskar, and Richard Socher. 2017. Regularizing and Optimizing LSTM Language Models.
+:::
+"""
+
+
+def test_citations_across_exports():
+    document = md2mdhtml(CITATIONS)
+    assert document.meta['cite_style'] == 'numeric' and '<div class="bibliography">' in document and 'data-suffix=", p. 33"' in document
+    assert '<dt id="howard2018">Howard and Ruder, 2018</dt>' in document   # the label is symbolic data; finished output decides its display
+    numeric = mdhtml2html(document)
+    assert '[<a href="#howard2018">1</a>]' in numeric and 'see [<a href="#howard2018">1, p. 33</a>; <a href="#merity2017">2</a>]' in numeric
+    assert '<a href="#howard2018">Howard and Ruder [1]</a>' in numeric and '<dt id="howard2018" data-id="howard2018">[1]</dt>' in numeric and '<dt id="merity2017" data-id="merity2017">[2]</dt>' in numeric
+    author_year = mdhtml2html(document, cite_style='author-year')
+    assert '(<a href="#howard2018">Howard and Ruder, 2018</a>)' in author_year and '<a href="#howard2018">Howard and Ruder (2018)</a>' in author_year
+    assert '(<a href="#howard2018">2018</a>)' in author_year and '<dt' not in author_year and '<dd id="howard2018" data-id="howard2018">' in author_year
+    ids = mdhtml2html(document, refs='ids')
+    assert '<dt id="howard2018" data-id="howard2018">Howard and Ruder, 2018</dt>' in ids and 'class="xref">howard2018</a>' in ids
+    gfm = md2gfm(CITATIONS, cite_style='author-year')
+    assert 'See (Howard and Ruder, 2018), (see Howard and Ruder, 2018, p. 33; Merity et al., 2017), Howard and Ruder (2018), and (2018).' in gfm
+    assert '<a name="howard2018"></a>Jeremy Howard' in gfm and '[@' not in gfm and ':::' not in gfm
+    assert r'\[1\] Jeremy Howard' in md2gfm(CITATIONS)
+    typst = mdhtml2typst(document)
+    assert r'See \[1\], see \[1, p. 33; 2\], Howard and Ruder \[1\], and \[1\].' in typst and r'\[2\] #metadata(none) <merity2017>Stephen Merity' in typst
+    assert 'See (Howard and Ruder, 2018)' in mdhtml2typst(md2mdhtml(CITATIONS.split('---\n', 2)[2]))
+    assert r'\[1\] #metadata(none) <howard2018>' in mdhtml2typst(md2mdhtml(CITATIONS.split('---\n', 2)[2]), cite_style='numeric')
+    assert normalize_html(md2mdhtml(mdhtml2md(document))) == normalize_html(document)
+    parsed = parse_md(CITATIONS)
+    entries = parsed.blocks[-1]['entries']
+    assert parsed.blocks[-1]['type'] == 'bibliography' and entries[0]['label_text'] == 'Howard and Ruder, 2018' and entries[1]['body'][0]['type'] == 'paragraph'
+    index = parsed.index()
+    assert index.cite_style == 'numeric' and index.targets['merity2017']['kind'] == 'citation'
+    assert ''.join(n['text'] for n in index.resolve([dict(target='howard2018', tokens=['text'], prefix='', suffix=', p. 33')])) == 'Howard and Ruder [1, p. 33]'
+    bibliography = CITATIONS[CITATIONS.index(':::'):]
+    for bad, message in [('[@howard2018; @sec-a]', 'mixes'), ('[@howard2018]{ref=page}', 'ref=page'), ('[see @howard2018]{ref=text}', 'prefix')]:
+        with pytest.raises(ValueError, match=message): mdhtml2html(md2mdhtml(f'## A {{#sec-a}}\n\n{bad}\n\n{bibliography}'))
+    with pytest.raises(ValueError, match='cite_style'): mdhtml2html(md2mdhtml('---\ncite_style: harvard\n---\n\ntext'))
diff --git a/tests/test_focused.py b/tests/test_focused.py
index d90c7f8..67a0b1a 100644
--- a/tests/test_focused.py
+++ b/tests/test_focused.py
@@ -148,8 +148,8 @@ def test_ref_syntax():
 
 def test_ref_non_matches():
     assert 'data-ref' not in md2mdhtml('mail [user@host] today')     # no space before @
-    assert 'data-ref' not in md2mdhtml('odd [@sec x] here')          # id stops at space
-    assert 'data-ref' not in md2mdhtml('a [@sec-a; Two @sec-b] b')   # prefix only allowed solo
+    assert 'data-suffix=" x"' in md2mdhtml('odd [@sec x] here')       # id stops at space; the rest is suffix text
+    assert '<a href="#sec-b" data-ref="">Two</a>' in md2mdhtml('a [@sec-a; Two @sec-b] b')   # prefix text per item
     assert '<a href="/u">@sec-x</a>' in md2mdhtml('[@sec-x](/u)')    # links win
     assert '[@]' in md2mdhtml('empty [@] ref')