From 610a09e4be2c651f2b0f9d48bf4dafb68da5e48c Mon Sep 17 00:00:00 2001
From: Jack Hogan <jackhogan4@gmail.com>
Date: Wed, 28 Oct 2026 17:17:23 +0000
Subject: [PATCH] Add citations: bibliography terms as `cite` targets,
 author-year and numeric styles

A definition list inside a `::: {.references}` container is a bibliography. Its id-bearing terms register as `cite` targets instead of `text`. `[@key]` renders parenthetically, "(Dai and Le, 2015)"; `{ref=text}` textually, "Dai and Le (2015)"; `-@` as the bare label. A group of citations shares one pair of parentheses with "; " between entries. `page`, `leaf` and `rel` are errors on a citation.

`cite='numeric'` on mdhtml2html, md2gfm and mdhtml2typst numbers the entries in list order, renders "[1]", "[1, 3]" and "Dai and Le [1]", and relabels each term with its number. The HTML exporter wraps every citation in `span.cite` so a page can attach a hover card from the entry its link targets.

`references` joins `math` and `footnotes` as a reserved class word. docs/DIALECT.md gains a citations section; the parser is unchanged.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
---
 README.md               |  6 ++-
 docs/DIALECT.md         | 35 ++++++++++++++++--
 py/src/lib.rs           | 30 +++++++++++++--
 python/mdhtml/export.py |  6 ++-
 python/mdhtml/md.py     | 34 +++++++++++++----
 python/mdhtml/typst.py  | 48 ++++++++++++++++++------
 src/export_html.rs      | 74 ++++++++++++++++++++++++++++++++-----
 src/resolve.rs          | 81 ++++++++++++++++++++++++++++++++++-------
 tests/test_export.py    | 55 ++++++++++++++++++++++++++++
 9 files changed, 317 insertions(+), 52 deletions(-)

diff --git a/README.md b/README.md
index 3da948d..24e3a72 100644
--- a/README.md
+++ b/README.md
@@ -32,7 +32,7 @@ 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. `[@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. A reference to a term of a definition list inside a `::: {.references}` container is a citation, rendered by [its own rules](docs/DIALECT.md#citations).
 - 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>`. Its alt text becomes the `<figcaption>`. The image's id and classes move to the figure. The image has `alt=""` to avoid announcing the caption twice through assistive technology.
 - Inline footnotes: pandoc-style `^[an inline note]`, numbered together with `[^id]` references.
 
@@ -494,6 +494,8 @@ In `resolve` mode, cross-references become links with resolved text. `[@sec-pay]
 
 `reftypes=dict(exh=('Exhibit', 'Exhibits'))` adds prefix words to the built-in `sec`, `fig`, `tbl`, and `eq` types. Missing targets, unknown tokens, and unknown types that need a prefix raise errors. The Word-only `page` and `rel` variants display the full number.
 
+Citations are references to the terms of a definition list inside a `::: {.references}` container. Each term is the "Author, year" label with the citation key as its id. `[@dai2015]` renders "(Dai and Le, 2015)", `[@a; @b]` renders "(A; B)", `[@dai2015]{ref=text}` renders "Dai and Le (2015)", and `[-@dai2015]` renders the label alone, for an author who writes the parentheses. `cite='numeric'` numbers the entries in list order instead: "[1]", "[1, 3]", "Dai and Le [1]", with each term relabelled to its number. Every baked citation sits in `<span class="cite">`.
+
 Two other modes support previews and drafts:
 
 - `refs='ids'` displays each target id as a link, such as `<a href="#sec-pay" class="xref">sec-pay</a>`. Authored text remains as a prefix. Variants are ignored. This mode does not validate references. Headings are numbered when the argument or frontmatter supplies a scheme. It never numbers headings automatically. Captions remain as authored. Use it when targets can be outside the fragment being previewed, where numbering would otherwise restart for each fragment.
@@ -570,7 +572,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`.
+- 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 render as in HTML, in the `cite` style.
 - Heading numbers become part of the heading text. Heading attribute lists are removed.
 - A `: caption` line immediately after a table becomes a "Table 1: caption" paragraph.
 - 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 76cb39f..ad1c51c 100644
--- a/docs/DIALECT.md
+++ b/docs/DIALECT.md
@@ -399,12 +399,41 @@ 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 the id-bearing headings, paragraphs, figures, tables, display equations, spans, and definition terms. Headings resolve to a heading number ("Section 1"), figures, tables and equations to a caption number ("Table 2", "Equation 3"), and paragraphs only through `{ref=text}`. Spans and definition terms resolve to their own text with no prefix word, so `the [@def-term] period` reads as running prose citing the defined term, and a rendering variant that needs a number (`leaf`, `rel`) is an error for them. Converters with a link mechanism link the cited text back to its definition site; `md2gfm` renders the text alone.
+Reference targets are the id-bearing headings, paragraphs, figures, tables, display equations, spans, and definition terms. A definition term inside a `.references` container is a citation target, rendered by the rules in the citations section below. Headings resolve to a heading number ("Section 1"), figures, tables and equations to a caption number ("Table 2", "Equation 3"), and paragraphs only through `{ref=text}`. Spans and definition terms resolve to their own text with no prefix word, so `the [@def-term] period` reads as running prose citing the defined term, and a rendering variant that needs a number (`leaf`, `rel`) is an error for them. Converters with a link mechanism link the cited text back to its definition site; `md2gfm` renders the text alone.
 
 The shipped exporters lower references from one shared vocabulary (`mdhtml.export`) at three levels of liveness: `mdhtml2docx` bakes REF fields Word keeps live, `mdhtml2html` bakes links with computed text, and `md2gfm` bakes plain text. Prefix words come from `REFTYPES` (`sec`, `fig`, `tbl`; 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
+
+A bibliography is a definition list inside a `::: {.references}` container. Each term is the citation label, written as "Author, year", and carries the citation key as its id. The definition is the entry.
+
+```markdown
+::: {.references}
+Dai and Le, 2015 {#dai2015}
+: Andrew M. Dai and Quoc V. Le. 2015. [Semi-supervised Sequence Learning](http://arxiv.org/abs/1511.01432). *Advances in Neural Information Processing Systems (NIPS '15)*.
+:::
+```
+
+```html
+<div class="references"><dl><dt id="dai2015">Dai and Le, 2015</dt><dd>Andrew M. Dai and Quoc V. Le. 2015. <a href="http://arxiv.org/abs/1511.01432">Semi-supervised Sequence Learning</a>. <em>Advances in Neural Information Processing Systems (NIPS '15)</em>.</dd></dl></div>
+```
+
+A reference to such a term is a citation. It uses the cross-reference grammar and carrier unchanged: the `references` class on the container makes its terms citation targets, and the parser emits nothing new. Converters render a citation by these rules instead of the term-text rule:
+
+```markdown
+[@dai2015], [see @dai2015], and [@mou2016; @dai2015].
+[@dai2015]{ref=text} and [-@dai2015].
+```
+
+- The default form is parenthetical: "(Dai and Le, 2015)". Prefix text goes inside the parentheses: "(see Dai and Le, 2015)". A group renders inside one pair of parentheses with "; " between entries: "(Mou et al., 2016; Dai and Le, 2015)".
+- `text` renders the textual form, "Dai and Le (2015)". The label splits at its last ", " into author and year. A label with no ", " renders as written in every form.
+- `bare` renders the label with no parentheses, "Dai and Le, 2015", for an author who writes the parentheses and any prefix text themselves.
+- `page`, `leaf`, and `rel` are errors for a citation: an entry has no page or outline number.
+
+A converter may offer a numeric style, which numbers the entries in list order. `mdhtml2html(cite='numeric')` renders the default form as "[1]", a group as "[1, 3]", the textual form as "Dai and Le [1]", and the bare form as "[1]", and relabels each term with its number. `md2gfm` and `mdhtml2typst` take the same `cite` option. The HTML exporter wraps every citation in `<span class="cite">` with its links inside, so a page can attach a hover card from the entry each link targets.
+
 ## Raw HTML and md in HTML
 
 Raw HTML participates in the final whole-fragment HTML5 parse. There is no separate balance operation.
@@ -599,7 +628,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.
+- **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. A reference whose target is a term in a `.references` container is a citation and renders by the citations section's rules.
 - **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.
@@ -607,7 +636,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 `references` on a bibliography's container — 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/py/src/lib.rs b/py/src/lib.rs
index dbefe47..3eca993 100644
--- a/py/src/lib.rs
+++ b/py/src/lib.rs
@@ -404,6 +404,21 @@ impl Resolver {
 
     fn set_capnum(&mut self, id: &str, label: &str, n: u32) { self.inner.set_capnum(id, label, n); }
 
+    /// Record a bibliography entry's number, for the numeric citation style.
+    fn set_citenum(&mut self, id: &str, n: u32) { self.inner.set_citenum(id, n); }
+
+    /// How citations render: `'author-year'` (the default) or `'numeric'`.
+    fn set_cite_style(&mut self, style: &str) -> PyResult<()> { self.inner.set_cite_style(cite_style(style)?); Ok(()) }
+
+    /// Is `tgt` a bibliography entry?
+    fn is_cite(&self, tgt: &str) -> bool { self.inner.is_cite(tgt) }
+
+    /// The `(open, close)` text an exporter puts around a citation, or a group of them.
+    fn cite_wrap(&self, tokens: HashSet<String>) -> (String, String) { let (o, c) = self.inner.cite_wrap(&tokens); (o.to_string(), c.to_string()) }
+
+    /// The separator for a group of citations, or None when any target is not one.
+    fn cite_sep(&self, tgts: Vec<String>) -> Option<String> { self.inner.cite_sep(&tgts).map(str::to_string) }
+
     /// Raise for a reference to an unknown target id.
     fn check(&self, tgt: &str) -> PyResult<()> { self.inner.check(tgt).map_err(vr) }
 
@@ -418,6 +433,13 @@ impl Resolver {
     }
 }
 
+/// A `cite=` option value as a `CiteStyle`.
+fn cite_style(s: &str) -> PyResult<resolve::CiteStyle> {
+    match s {
+        "author-year" => Ok(resolve::CiteStyle::AuthorYear), "numeric" => Ok(resolve::CiteStyle::Numeric), _ => Err(vr(format!("unknown cite style {s:?}")))
+    }
+}
+
 #[pymodule]
 fn _native(m: &Bound<'_, PyModule>) -> PyResult<()> {
     m.add_function(wrap_pyfunction!(md2mdhtml, m)?)?;
@@ -790,11 +812,11 @@ fn attr_node<'py>(py: Python<'py>, attrs: &Attr) -> PyResult<Bound<'py, PyDict>>
 // ---------------------------------------------------------------------------
 
 #[pyfunction]
-#[pyo3(signature = (src, reftypes, number_headings, hl, toc, refs, id_prefix, fn_salt, hl_lang, code_wrap, hl_fn, auto_ids, gh_ids))]
+#[pyo3(signature = (src, reftypes, number_headings, hl, toc, refs, id_prefix, fn_salt, hl_lang, code_wrap, hl_fn, auto_ids, gh_ids, cite))]
 fn export_html(
     py: Python<'_>, src: &str, 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>)> {
+    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, cite: &str) -> PyResult<(String, Vec<String>)> {
     use mdhtml::export_html::{HlMode, HtmlExportOptions, NumberHeadings, RefsMode};
     let number_headings = match number_headings {
         None => None,
@@ -829,7 +851,7 @@ fn export_html(
     }, toc, refs: match refs {
         "ids" => RefsMode::Ids, "lenient" => RefsMode::Lenient, _ => RefsMode::Resolve
     }, 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: cite_style(cite)? };
     let result = if hl_lang.is_none() && code_wrap.is_none() && hl_fn.is_none() { py.detach(|| mdhtml::export_html::export_html(src, &opts)) }
     else { mdhtml::export_html::export_html(src, &opts) };
     if let Some(e) = hook_err.into_inner().unwrap() { return Err(e); }
diff --git a/python/mdhtml/export.py b/python/mdhtml/export.py
index 177fdc6..62ab430 100644
--- a/python/mdhtml/export.py
+++ b/python/mdhtml/export.py
@@ -94,7 +94,7 @@ 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: str = "author-year") -> Html:
     """Lower MDHTML (a string or DocumentFragment; never mutated) to finished HTML: cross-references
     baked as links, headings, captions and equations numbered, `{=html}` raw data spliced, `colwidths` lowered,
     and code highlighted. A `div[data-panel]` with open/closed disclosure lowers to `<details>`,
@@ -123,12 +123,14 @@ 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` chooses how citations (references to a `.references` list's terms) render: `'author-year'`, the
+    default, or `'numeric'`, which numbers the entries in list order and relabels them.
     Returns an `Html` str carrying `.warnings`; `dest` also writes it to a file."""
     if refs not in ("resolve", "ids", "lenient"): raise ValueError(f"unknown refs mode {refs!r}")
     number_headings = _headnums(getattr(src, 'meta', {}), number_headings)
     if not isinstance(src, str): src = src.to_html()
     hl_fn = None if hl is None else _hl_fn(hl)
-    out, warnings = _export_html(src, reftypes, number_headings, hl, toc, refs, id_prefix, fn_salt, hl_lang, code_wrap, hl_fn, auto_ids, gh_ids)
+    out, warnings = _export_html(src, reftypes, number_headings, hl, toc, refs, id_prefix, fn_salt, hl_lang, code_wrap, hl_fn, auto_ids, gh_ids, cite)
     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 d9c5bec..3769dab 100644
--- a/python/mdhtml/md.py
+++ b/python/mdhtml/md.py
@@ -20,6 +20,7 @@
 _DIV_FENCE = re.compile(r":{3,}\s*")
 _SETEXT = re.compile(r"\s{0,3}(=+|-+)\s*")
 _DEF_LINE = re.compile(r" {0,3}:\s")
+_ATTR_ID = re.compile(r"#([A-Za-z0-9_\-.:]+)")
 
 
 def _normalize_offsets(src: str) -> tuple[str, list[int]]:
@@ -63,8 +64,10 @@ def _is_caption(line):
 
 class _GfmExporter:
     def __init__(self, reftypes, number_headings, math, implicit_figures, templates=None, tmpl=None,
-        raw=("md",), imgdir=None, imgbase=None):
+        raw=("md",), imgdir=None, imgbase=None, cite="author-year"):
         self.res = Resolver(reftypes)
+        self.res.set_cite_style(cite)
+        self.numeric, self.citenum = cite == "numeric", {}
         self.number_headings, self.math, self.implicit_figures = number_headings, math, implicit_figures
         self.templates, self.tmpl = [astuple(t) if is_dataclass(t) else tuple(t) for t in templates or []], tmpl
         self.raw, self.imgdir, self.imgbase = raw, imgdir, imgbase
@@ -83,7 +86,11 @@ def run(self, src):
         heads = {n["start"] for n in nodes}
         for b in spans:
             if b["type"] in ("figure", "template_token") and b["depth"] and not self._bare(b, heads): b["type"] = "paragraph"
-        for a in _anchors(src, math=self.math, templates=self.templates): self.res.register(a['id'], a['kind'], a['text'])
+        for a in _anchors(src, math=self.math, templates=self.templates):
+            self.res.register(a['id'], a['kind'], a['text'])
+            if a['kind'] == 'cite' and self.numeric:
+                self.citenum[a['id']] = n = len(self.citenum) + 1
+                self.res.set_citenum(a['id'], n)
         self._index(spans, nodes)
         span_ends = {(n["end"], n["depth"] + 1) for n in nodes if n["type"] == "span"}
         for n in nodes:
@@ -199,11 +206,18 @@ def _index(self, spans, nodes):
                 if i := b.get("id"): res.set_headnum(i, d, nums.full(b['level'] - 1))
 
     def _xref(self, x, parsed):
-        out = []
-        for (sep, pre, plural), (r, toks) in zip(group_plan([r["target"].split("-")[0] for r, _ in parsed]), parsed):
+        tgts = [r["target"] for r, _ in parsed]
+        if (sep := self.res.cite_sep(tgts)) is not None:
+            # A group of citations shares one pair of parentheses or brackets, with the style's separator between entries.
+            open_, close = self.res.cite_wrap(parsed[0][1])
+            plan = [("" if i == 0 else sep, True, False) for i in range(len(parsed))]
+        else: open_, close, plan = "", "", group_plan([t.split("-")[0] for t in tgts])
+        out = [open_]
+        for (sep, pre, plural), (r, toks) in zip(plan, parsed):
             out.append(sep)
             if pre: out.append(self.res.prefix(r["prefix"] or "", r["target"], toks, plural))
             out.append(self.res.core(r["target"], toks))
+        out.append(close)
         self.inline.append((x["start"], x["end"], "".join(out)))
 
     def _replace_lines(self, i, j, repl):
@@ -231,7 +245,11 @@ def _block(self, b):
             for ln in range(s, e):
                 lb = self.lines[ln].encode()
                 if _DEF_LINE.match(self.lines[ln]) or (sp := _trailing_attr_span(self.lines[ln])) is None: continue
-                self.block.append((self.starts[ln] + len(lb[:sp[0]].rstrip()), self.starts[ln] + len(lb), ""))
+                # In the numeric citation style a bibliography entry's term becomes its number.
+                m = _ATTR_ID.search(lb[sp[0]:sp[1]].decode())
+                if m and (num := self.citenum.get(m[1])) is not None:
+                    self.block.append((self.starts[ln] + len(lb) - len(lb.lstrip()), self.starts[ln] + len(lb), f"[{num}]"))
+                else: self.block.append((self.starts[ln] + len(lb[:sp[0]].rstrip()), self.starts[ln] + len(lb), ""))
         elif t == "template_token" and self.tmpl:
             cs, ce = self._chars(s, e)
             self.block.append((cs, ce, self.tmpl(b) + "\n"))
@@ -311,9 +329,9 @@ def _table(self, b, s, e):
             self.block.append((p, p, f"\n{label} {n}\n"))
 
 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",), imgdir=None, link=None) -> Md:
+    implicit_figures: bool = False, templates=None, tmpl=None, raw: tuple = ("md",), imgdir=None, link=None, cite: str = "author-year") -> Md:
     """Lower Markdown to portable GFM-plus-footnotes by rewriting mdhtml-specific constructs in
-    place: cross-references become plain text, headings, captions and equations are numbered, attribute
+    place: cross-references become plain text (citations in the `cite` style, author-year or numeric), headings, captions and equations are numbered, attribute
     lists and definitions are stripped, and raw data in the formats named by `raw` is spliced
     (all other formats drop; `('md', 'html')` suits targets that render inline HTML, like GFM).
     With `imgdir`, each base64 data-URI image is written to a content-hashed file in that
@@ -331,7 +349,7 @@ def md2gfm(src, dest=None, reftypes: dict | None = None, number_headings=None, m
     number_headings = _headnums(dict(_frontmatter_meta(src)), number_headings)
     imgbase = Path(dest).parent if dest is not None else Path(".")
     ex = _GfmExporter(reftypes, number_headings, math, implicit_figures, templates, tmpl,
-        raw=raw, imgdir=None if imgdir is None else Path(imgdir), imgbase=imgbase)
+        raw=raw, imgdir=None if imgdir is None else Path(imgdir), imgbase=imgbase, cite=cite)
     if link is not None or imgdir is not None:
         def url(node):
             old = node['url']
diff --git a/python/mdhtml/typst.py b/python/mdhtml/typst.py
index 77a302f..e0a0209 100644
--- a/python/mdhtml/typst.py
+++ b/python/mdhtml/typst.py
@@ -64,8 +64,10 @@ def __getnewargs__(self): return (str(self), self.warnings)
 
 
 class _TypstExporter(Resolver):
-    def __init__(self, reftypes, number_headings, tmpl, table_styles=None):
+    def __init__(self, reftypes, number_headings, tmpl, table_styles=None, cite="author-year"):
         super().__init__(reftypes)
+        self.set_cite_style(cite)
+        self.numeric, self.citenum = cite == "numeric", {}
         self.number_headings, self.tmpl = number_headings, tmpl
         self.table_styles = {k.lower(): v for k, v in (table_styles or {}).items()}
         self.warnings, self.headids, self.fnotes, self.fnotes_done = [], set(), {}, set()
@@ -74,13 +76,22 @@ def __init__(self, reftypes, number_headings, tmpl, table_styles=None):
     def run(self, root):
         for e in _walk_all(root):
             if not (i := e.attrs.get("id")): continue
-            kind = target_kind(e.name, e.attrs.get("class", ""))
+            kind = "cite" if e.name == "dt" and self._in_references(e) else target_kind(e.name, e.attrs.get("class", ""))
             if e.name in _HEADS: self.headids.add(i)
             if e.name == "div" and kind == "caption": self.need_eq_nums = True
+            if kind == "cite" and self.numeric:
+                self.citenum[i] = n = len(self.citenum) + 1
+                self.set_citenum(i, n)
             self.register(i, kind, _text(e))
         self._harvest_footnotes(root)
         return self._blocks(root)
 
+    def _in_references(self, el):
+        "Is `el` inside a `div.references`, the bibliography container whose terms are citation targets?"
+        while isinstance(el := el.parent, Element):
+            if el.name == "div" and el.has_class("references"): return True
+        return False
+
     # ---- blocks ------------------------------------------------------------
 
     def _blocks(self, el):
@@ -154,7 +165,9 @@ def _dl(self, el):
             if c.name == "dt":
                 if seen_dd: terms, seen_dd = [], False
                 lab = f"#metadata(none) <{c.attrs['id']}>" if c.attrs.get("id") else ""
-                terms.append(lab + self._inline(c))
+                # In the numeric citation style a bibliography entry's term becomes its number.
+                num = self.citenum.get(c.attrs.get("id"))
+                terms.append(lab + (_esc(f"[{num}]") if num is not None else self._inline(c)))
             elif c.name == "dd":
                 seen_dd = True
                 body = self._blocks(c) if any(x.name in _BLOCKS for x in c.element_children) else self._inline(c)
@@ -272,7 +285,11 @@ def _link(self, el):
         if "data-ref" in el.attrs:
             tgt = (el.attrs.get("href") or "#")[1:]
             self.check(tgt)
-            return self._ref(tgt, ref_tokens(el.attrs.get("data-ref")), el.to_text().strip())
+            tokens = ref_tokens(el.attrs.get("data-ref"))
+            ref = self._ref(tgt, tokens, el.to_text().strip())
+            if not self.is_cite(tgt): return ref
+            open_, close = self.cite_wrap(tokens)
+            return _esc(open_) + ref + _esc(close)
         h, body = el.attrs.get("href") or "", self._inline(el)
         if h.startswith("#"):
             if h[1:] in self.kinds: return f"#link(<{h[1:]}>)[{body}]"
@@ -282,16 +299,22 @@ def _link(self, el):
 
     def _group(self, el):
         anchors = [a for a in el.element_children if a.name == "a"]
-        types = [(a.attrs.get("href") or "#")[1:].split("-")[0] for a in anchors]
-        out = []
-        for a, (sep, pfx, plural) in zip(anchors, group_plan(types)):
-            tgt = (a.attrs.get("href") or "#")[1:]
-            self.check(tgt)
+        tgts = [(a.attrs.get("href") or "#")[1:] for a in anchors]
+        for tgt in tgts: self.check(tgt)
+        if (sep := self.cite_sep(tgts)) is not None:
+            # A group of citations shares one pair of parentheses or brackets, with the style's separator between entries.
+            open_, close = self.cite_wrap(ref_tokens(anchors[0].attrs.get("data-ref")))
+            plan = [("" if i == 0 else sep, True, False) for i in range(len(anchors))]
+        else: open_, close, plan = "", "", group_plan([t.split("-")[0] for t in tgts])
+        out = [_esc(open_)]
+        for a, tgt, (sep, pfx, plural) in zip(anchors, tgts, plan):
             out.append(sep + self._ref(tgt, ref_tokens(a.attrs.get("data-ref")), a.to_text().strip(), pfx, plural))
+        out.append(_esc(close))
         return "".join(out)
 
     def _ref(self, tgt, tokens, override, prefix=True, plural=False):
         variant = ref_variant(tokens)
+        if self.kinds[tgt] == "cite": return _esc(self.prefix(override, tgt, tokens)) + f"#link(<{tgt}>)[{_esc(self.core(tgt, tokens))}]"
         if self.kinds[tgt] == "text": return f"#link(<{tgt}>)[{_esc(self.core(tgt, tokens))}]"
         if variant == "text": return f"#link(<{tgt}>)[{_esc(self.idtext[tgt])}]"
         if self.kinds[tgt] == "block":
@@ -319,7 +342,8 @@ def _walk_all(el):
         yield from _walk_all(c)
 
 
-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: str = "author-year") -> Typst:
     """Lower MDHTML (a string or DocumentFragment; never mutated) to Typst markup: cross-references
     become native `@ref`s with `reftypes` supplements, heading numbering (a `SCHEMES` name or dict;
     `None` numbers automatically when a reference needs it) becomes a `set heading` rule, figures,
@@ -330,10 +354,12 @@ def mdhtml2typst(src, dest=None, reftypes: dict | None = None, number_headings=N
     order, case-insensitively) to extra Typst table arguments, e.g. `{'borderless table': 'stroke: none'}`.
     `prelude` text is prepended before the generated setup. `number_headings=None` takes the
     scheme from the input's metadata; `False` disables heading numbering.
+    `cite` chooses how citations render: `'author-year'` (the default) or `'numeric'`, numbering the
+    bibliography's entries in list order and relabelling them.
     Returns a `Typst` str carrying `.warnings`; `dest` also writes it to a file."""
     number_headings = _headnums(getattr(src, 'meta', {}), number_headings)
     if not isinstance(src, str): src = src.to_html()
-    ex = _TypstExporter(reftypes, number_headings, tmpl, table_styles)
+    ex = _TypstExporter(reftypes, number_headings, tmpl, table_styles, cite)
     body = ex.run(mdhtml2dom(src))
     parts = [prelude.rstrip()] if prelude else []
     if ex.has_math: parts.append(f'#import "{MITEX}": mi, mitex')
diff --git a/src/export_html.rs b/src/export_html.rs
index d75bf7c..d234547 100644
--- a/src/export_html.rs
+++ b/src/export_html.rs
@@ -8,7 +8,7 @@ use std::collections::{HashMap, HashSet};
 use fast5ever::{DOCUMENT, Dom, NodeId, parse_fragment};
 use unicode_properties::{GeneralCategoryGroup, UnicodeGeneralCategory};
 
-use crate::resolve::{self, HeadingNums, Resolver, target_kind};
+use crate::resolve::{self, CiteStyle, HeadingNums, Resolver, target_kind};
 
 const RAW_TYPE: &str = "application/vnd.mdhtml.raw";
 const HEADS: [&str; 6] = ["h1", "h2", "h3", "h4", "h5", "h6"];
@@ -38,7 +38,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: CiteStyle
 }
 
 /// Lower an MDHTML fragment to finished HTML; returns the markup and the
@@ -113,10 +113,11 @@ impl Exporter {
         for &e in &els {
             let Some(id) = self.dom.attr(e, "id").map(str::to_string) else { continue };
             let name = self.dom.tag(e).unwrap();
-            let kind = target_kind(name, self.dom.attr(e, "class").unwrap_or(""));
+            let kind = if name == "dt" && self.in_references(e) { Some("cite") } else { target_kind(name, self.dom.attr(e, "class").unwrap_or("")) };
             let text = norm_text(&self.dom, e);
             self.res.register(&id, kind, Some(&text));
         }
+        self.res.set_cite_style(opts.cite);
         let groups: Vec<NodeId> = els.iter().copied().filter(|&e| self.dom.attr(e, "data-refs").is_some()).collect();
         let grouped: HashSet<NodeId> = groups.iter().flat_map(|&g| self.dom.element_children(g)).filter(|&a| self.dom.tag(a) == Some("a")).collect();
         let singles: Vec<NodeId> =
@@ -143,9 +144,15 @@ impl Exporter {
             self.number_headings(&refs, opts)?;
             let figs: Vec<NodeId> = els.iter().copied().filter(|&e| matches!(self.dom.tag(e), Some("figure") | Some("table")) || self.equation(e)).collect();
             self.number_captions(&figs);
+            if opts.cite == CiteStyle::Numeric { self.number_cites(&els); }
             for &g in &groups { self.lower_group(g, opts)?; }
             for &a in &singles {
-                match self.resolve_ref(a, true, false) { Ok((p, core)) => self.set_ref(a, &format!("{p}{core}")), Err(e) => self.fallback(a, e, opts)? }
+                // A citation's wrapper is decided before baking, which drops the `data-ref` tokens it reads.
+                let cite = self.parse_ref(a).ok().filter(|(t, _)| self.res.is_cite(t)).map(|(_, t)| self.res.cite_wrap(&t));
+                match self.resolve_ref(a, true, false) {
+                    Ok((p, core)) => { self.set_ref(a, &format!("{p}{core}")); if let Some((open, close)) = cite { self.wrap_cite(a, open, close); } }
+                    Err(e) => self.fallback(a, e, opts)?,
+                }
             }
         }
         self.prefix_ids(&els, opts);
@@ -302,19 +309,25 @@ impl Exporter {
 
     fn lower_group(&mut self, span: NodeId, opts: &HtmlExportOptions) -> Result<(), String> {
         let anchors: Vec<NodeId> = self.dom.element_children(span).into_iter().filter(|&a| self.dom.tag(a) == Some("a")).collect();
-        let types: Vec<String> = anchors.iter().map(|&a| {
-            let href = self.dom.attr(a, "href").unwrap_or("#");
-            href.get(1..).unwrap_or("").split('-').next().unwrap_or("").to_string()
-        }).collect();
+        let tgts: Vec<String> = anchors.iter().map(|&a| self.dom.attr(a, "href").unwrap_or("#").get(1..).unwrap_or("").to_string()).collect();
+        let types: Vec<String> = tgts.iter().map(|t| t.split('-').next().unwrap_or("").to_string()).collect();
+        // A group of citations shares one pair of parentheses or brackets, with the style's separator between entries.
+        let cite = self.res.cite_sep(&tgts).map(|sep| (sep, self.parse_ref(anchors[0]).map(|(_, t)| self.res.cite_wrap(&t)).unwrap_or(("", ""))));
+        let plan: Vec<(&'static str, bool, bool)> = match cite {
+            Some((sep, _)) => (0..anchors.len()).map(|i| (if i == 0 { "" } else { sep }, true, false)).collect(), None => resolve::group_plan(&types)
+        };
         let mut out = Vec::new();
-        for ((sep, pre, plural), &a) in resolve::group_plan(&types).into_iter().zip(&anchors) {
+        if let Some((_, (open, _))) = cite && !open.is_empty() { out.push(self.dom.create_text(open)); }
+        for ((sep, pre, plural), &a) in plan.into_iter().zip(&anchors) {
             if !sep.is_empty() { out.push(self.dom.create_text(sep)); }
             match self.resolve_ref(a, pre, plural) {
                 Ok((p, core)) => { self.set_ref(a, &core); if !p.is_empty() { out.push(self.dom.create_text(&p)); } } Err(e) => self.fallback(a, e, opts)?
             }
             out.push(a);
         }
+        if let Some((_, (_, close))) = cite && !close.is_empty() { out.push(self.dom.create_text(close)); }
         self.dom.remove_attr(span, "data-refs").unwrap();
+        if cite.is_some() { self.dom.set_attr(span, "class", "cite").unwrap(); }
         self.dom.clear_children(span);
         for id in out { self.dom.append_child(span, id).unwrap(); }
         Ok(())
@@ -337,6 +350,49 @@ impl Exporter {
         self.dom.remove_attr(a, "data-ref").unwrap();
     }
 
+    /// Is `el` inside a `div.references`, the bibliography container whose
+    /// terms are citation targets?
+    fn in_references(&self, el: NodeId) -> bool {
+        let mut cur = self.dom.parent(el);
+        while let Some(p) = cur {
+            if self.dom.is_tag(p, "div", None) && self.dom.has_class(p, "references") { return true; }
+            cur = self.dom.parent(p);
+        }
+        false
+    }
+
+    /// Number the bibliography's terms in list order for the numeric
+    /// citation style, relabelling each with its number.
+    fn number_cites(&mut self, els: &[NodeId]) {
+        let mut n = 0;
+        for &e in els {
+            if self.dom.tag(e) != Some("dt") || !self.in_references(e) { continue; }
+            let Some(id) = self.dom.attr(e, "id").map(str::to_string) else { continue }; // only an entry with an id can be cited; one without takes no number
+            n += 1;
+            self.res.set_citenum(&id, n);
+            self.dom.clear_children(e);
+            let t = self.dom.create_text(&format!("[{n}]"));
+            self.dom.append_child(e, t).unwrap();
+        }
+    }
+
+    /// Wrap a baked citation anchor in `span.cite`, with the text the style
+    /// owns (`open`, `close`) around it.
+    fn wrap_cite(&mut self, a: NodeId, open: &str, close: &str) {
+        let parent = self.dom.parent(a).unwrap();
+        let span = self.dom.create_element("span", &[("class", "cite")]);
+        self.dom.insert_before(parent, span, Some(a)).unwrap();
+        if !open.is_empty() {
+            let t = self.dom.create_text(open);
+            self.dom.append_child(span, t).unwrap();
+        }
+        self.dom.append_child(span, a).unwrap();
+        if !close.is_empty() {
+            let t = self.dom.create_text(close);
+            self.dom.append_child(span, t).unwrap();
+        }
+    }
+
     /// In `Lenient` mode an unresolvable ref bakes as an id link plus a
     /// warning; otherwise its error ends the export.
     fn fallback(&mut self, a: NodeId, err: String, opts: &HtmlExportOptions) -> Result<(), String> {
diff --git a/src/resolve.rs b/src/resolve.rs
index 39eaf0a..44cc80e 100644
--- a/src/resolve.rs
+++ b/src/resolve.rs
@@ -31,6 +31,10 @@ pub fn reftypes() -> Vec<(&'static str, (&'static str, &'static str))> {
 
 const VARIANTS: [&str; 4] = ["page", "text", "leaf", "rel"];
 
+/// How citations render: "Author, year" labels, or numbers in bibliography order.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub enum CiteStyle { #[default] AuthorYear, Numeric }
+
 fn quoted_list(mut items: Vec<&String>) -> String {
     items.sort();
     let body = items.iter().map(|t| format!("'{t}'")).collect::<Vec<_>>().join(", ");
@@ -174,19 +178,20 @@ fn placeholders(lvl_text: &str) -> Vec<u32> {
 }
 
 /// Cross-reference resolution shared by exporters: a registry of targets and
-/// the baked text each reference resolves to. Kinds are `"block"` or
-/// `"caption"`.
+/// the baked text each reference resolves to. Kinds are `"block"`,
+/// `"caption"`, `"text"` and `"cite"`.
 #[derive(Debug, Clone)]
 pub struct Resolver {
     pub reftypes: HashMap<String, (String, String)>, pub kinds: HashMap<String, String>, pub idtext: HashMap<String, String>,
-    pub headnums: HashMap<String, (String, String)>, pub capnums: HashMap<String, (String, u32)>
+    pub headnums: HashMap<String, (String, String)>, pub capnums: HashMap<String, (String, u32)>, pub cite: CiteStyle, pub citenums: HashMap<String, u32>
 }
 
 impl Resolver {
     pub fn new(extra_reftypes: Option<HashMap<String, (String, String)>>) -> Resolver {
         let mut rt: HashMap<String, (String, String)> = reftypes().into_iter().map(|(k, (s, p))| (k.to_string(), (s.to_string(), p.to_string()))).collect();
         if let Some(extra) = extra_reftypes { rt.extend(extra); }
-        Resolver { reftypes: rt, kinds: HashMap::new(), idtext: HashMap::new(), headnums: HashMap::new(), capnums: HashMap::new() }
+        Resolver { reftypes: rt, kinds: HashMap::new(), idtext: HashMap::new(), headnums: HashMap::new(), capnums: HashMap::new(), cite: CiteStyle::default(),
+            citenums: HashMap::new() }
     }
 
     /// Record a target: its kind (when known) and its text.
@@ -199,17 +204,26 @@ impl Resolver {
 
     pub fn set_capnum(&mut self, id: &str, label: &str, n: u32) { self.capnums.insert(id.to_string(), (label.to_string(), n)); }
 
+    /// Record a bibliography entry's number, for the numeric citation style.
+    pub fn set_citenum(&mut self, id: &str, n: u32) { self.citenums.insert(id.to_string(), n); }
+
+    pub fn set_cite_style(&mut self, style: CiteStyle) { self.cite = style; }
+
+    /// Is `tgt` a bibliography entry?
+    pub fn is_cite(&self, tgt: &str) -> bool { self.kinds.get(tgt).map(String::as_str) == Some("cite") }
+
     /// Error for a reference to an unknown target id.
     pub fn check(&self, tgt: &str) -> Result<(), String> {
         if self.kinds.contains_key(tgt) { Ok(()) } else {
             Err(format!(
-                "cross-reference target #{tgt} not found (targets are headings, paragraphs, figures, tables, equations, spans, and definition terms with ids)"
+                "cross-reference target #{tgt} not found (targets are headings, paragraphs, figures, tables, equations, spans, definition terms, and bibliography entries with ids)"
             ))
         }
     }
 
     /// A reference's baked text, without any prefix word.
     pub fn core(&self, tgt: &str, tokens: &HashSet<String>) -> Result<String, String> {
+        if self.is_cite(tgt) { return self.cite_core(tgt, tokens); }
         let variant = ref_variant(tokens);
         if variant == "text" || (variant == "full" && self.kinds.get(tgt).map(String::as_str) == Some("text")) { return Ok(self.idtext[tgt].clone()); }
         if self.kinds.get(tgt).map(String::as_str) == Some("caption") {
@@ -223,11 +237,46 @@ impl Resolver {
         Ok(num.strip_suffix('.').map_or(num.clone(), str::to_string)) // caption "1.2." cites as "Section 1.2": mid-sentence references drop the trailing dot
     }
 
+    /// A citation's text: the entry's "Author, year" label, "Author (year)"
+    /// for the `text` variant, or its number in the numeric style ("Author
+    /// [n]" for `text`). A label with no ", " is used as written.
+    fn cite_core(&self, tgt: &str, tokens: &HashSet<String>) -> Result<String, String> {
+        let variant = ref_variant(tokens);
+        if matches!(variant.as_str(), "page" | "leaf" | "rel") {
+            return Err(format!("citation #{tgt} has no page or outline number; use the default form, {{ref=text}} or -@"));
+        }
+        let label = &self.idtext[tgt];
+        let (author, year) = match label.rsplit_once(", ") { Some((a, y)) => (a, Some(y)), None => (label.as_str(), None) };
+        if self.cite == CiteStyle::Numeric {
+            let n = self.citenums.get(tgt).ok_or_else(|| format!("citation #{tgt} has no number; the exporter did not number the bibliography"))?;
+            return Ok(if variant == "text" { format!("{author} [{n}]") } else { n.to_string() });
+        }
+        Ok(match year { Some(y) if variant == "text" => format!("{author} ({y})"), _ => label.clone() })
+    }
+
+    /// The text an exporter puts around a citation, or a group of them:
+    /// parentheses for the default author-year form, brackets for every
+    /// numeric form but `text`, and nothing otherwise.
+    pub fn cite_wrap(&self, tokens: &HashSet<String>) -> (&'static str, &'static str) {
+        let variant = ref_variant(tokens);
+        match self.cite {
+            CiteStyle::Numeric if variant != "text" => ("[", "]"), CiteStyle::AuthorYear if variant == "full" && !tokens.contains("bare") => ("(", ")"),
+            _ => ("", "")
+        }
+    }
+
+    /// The separator for a group whose targets are all bibliography entries:
+    /// `"; "` between labels, `", "` between numbers. `None` for other groups.
+    pub fn cite_sep(&self, tgts: &[String]) -> Option<&'static str> {
+        if tgts.is_empty() || !tgts.iter().all(|t| self.is_cite(t)) { return None; }
+        Some(if self.cite == CiteStyle::Numeric { ", " } else { "; " })
+    }
+
     /// Prefix text before a reference: `override` text, the type's prefix
-    /// word, or nothing for bare and caption refs.
+    /// word, or nothing for bare, caption, text and citation refs.
     pub fn prefix(&self, override_text: &str, tgt: &str, tokens: &HashSet<String>, plural: bool) -> Result<String, String> {
         if !override_text.is_empty() { return Ok(format!("{override_text} ")); }
-        if tokens.contains("bare") || matches!(self.kinds.get(tgt).map(String::as_str), Some("caption" | "text")) { return Ok(String::new()); }
+        if tokens.contains("bare") || matches!(self.kinds.get(tgt).map(String::as_str), Some("caption" | "text" | "cite")) { return Ok(String::new()); }
         let t = tgt.split('-').next().unwrap_or("");
         let Some((singular, plural_word)) = self.reftypes.get(t) else {
             return Err(format!("unknown reference type '{t}'; pass reftypes= to define its prefix"));
@@ -253,8 +302,8 @@ pub fn target_kind(name: &str, classes: &str) -> Option<&'static str> {
 /// `(id, kind, text)` rows in the `Resolver::register` vocabulary.
 pub fn doc_anchors(doc: &Document) -> Vec<(String, &'static str, String)> {
     let mut out = Vec::new();
-    for b in &doc.blocks { anchor_block(b, &mut out); }
-    for f in &doc.footnotes { for b in &f.blocks { anchor_block(b, &mut out); } }
+    for b in &doc.blocks { anchor_block(b, false, &mut out); }
+    for f in &doc.footnotes { for b in &f.blocks { anchor_block(b, false, &mut out); } }
     out
 }
 
@@ -262,7 +311,9 @@ fn push_anchor(attrs: &Attr, kind: &'static str, text: String, out: &mut Vec<(St
     if let Some(id) = &attrs.id { out.push((id.clone(), kind, text.split_whitespace().collect::<Vec<_>>().join(" "))); }
 }
 
-fn anchor_block(b: &Block, out: &mut Vec<(String, &'static str, String)>) {
+/// `in_refs` is set inside a `.references` div, where definition terms are
+/// bibliography entries (`cite` targets) rather than defined terms.
+fn anchor_block(b: &Block, in_refs: bool, out: &mut Vec<(String, &'static str, String)>) {
     match b {
         Block::PanelTitle { attrs, children } => {
             push_anchor(attrs, "text", inlines_text(children), out);
@@ -286,14 +337,18 @@ fn anchor_block(b: &Block, out: &mut Vec<(String, &'static str, String)>) {
         Block::DefinitionList { items, .. } => {
             for item in items {
                 for t in &item.terms {
-                    push_anchor(&t.attrs, "text", inlines_text(&t.inlines), out);
+                    push_anchor(&t.attrs, if in_refs { "cite" } else { "text" }, inlines_text(&t.inlines), out);
                     anchor_inlines(&t.inlines, out);
                 }
                 for d in &item.definitions { anchor_inlines(d, out); }
             }
         }
-        Block::BlockQuote { children, .. } | Block::Div { children, .. } => { for c in children { anchor_block(c, out); } }
-        Block::List { items, .. } => { for item in items { for c in &item.blocks { anchor_block(c, out); } } }
+        Block::Div { attrs, children } => {
+            let refs = in_refs || attrs.classes.iter().any(|c| c == "references");
+            for c in children { anchor_block(c, refs, out); }
+        }
+        Block::BlockQuote { children, .. } => { for c in children { anchor_block(c, in_refs, out); } }
+        Block::List { items, .. } => { for item in items { for c in &item.blocks { anchor_block(c, in_refs, out); } } }
         _ => {}
     }
 }
diff --git a/tests/test_export.py b/tests/test_export.py
index 091be02..0ae693d 100644
--- a/tests/test_export.py
+++ b/tests/test_export.py
@@ -503,3 +503,58 @@ def test_equation_numbering():
     above = '{: #eq-above}\n\\[\nq = r\n\\]\n\nSee [@eq-above].\n'
     assert md2gfm(above) == '\\[\nq = r\n\\tag{1}\n\\]\n\nSee Equation 1.\n'                 # an IAL above the opener
     assert md2gfm('\\[\n{: a=b}\n') == '\\[\n{: a=b}\n'                                      # unclosed: an IAL-shaped last line is TeX
+
+
+CITATIONS = r'''Fine-tuning fails between unrelated tasks [@mou2016]. [@dai2015]{ref=text} fine-tune a language model, as do others [see @dai2015] and [@dai2015; @long2015a]. An unattributed note [-@anon] agrees ([-@mou2016]).
+
+## References
+
+::: {.references}
+Mou et al., 2016 {#mou2016}
+: Lili Mou and others. 2016. How Transferable are Neural Networks in NLP Applications?
+
+Dai and Le, 2015 {#dai2015}
+: Andrew M. Dai and Quoc V. Le. 2015. *Semi-supervised Sequence Learning*.
+
+Long et al., 2015a {#long2015a}
+: Jonathan Long, Evan Shelhamer, and Trevor Darrell. 2015a. Fully convolutional networks.
+
+Anonymous {#anon}
+: An unattributed note.
+:::
+'''
+
+
+def test_citations():
+    doc = md2mdhtml(CITATIONS)
+    assert not doc.warnings and '<div class=\"references\">' in doc   # the parser emits nothing new: the class is the marker
+    html = mdhtml2html(doc, number_headings=False)
+    assert 'tasks <span class="cite">(<a href="#mou2016">Mou et al., 2016</a>)</span>.' in html
+    assert '<span class="cite"><a href="#dai2015">Dai and Le (2015)</a></span> fine-tune' in html
+    assert '<span class="cite">(<a href="#dai2015">see Dai and Le, 2015</a>)</span>' in html
+    assert '<span class="cite">(<a href="#dai2015">Dai and Le, 2015</a>; <a href="#long2015a">Long et al., 2015a</a>)</span>' in html
+    assert 'note <span class="cite"><a href="#anon">Anonymous</a></span> agrees (<span class="cite"><a href="#mou2016">Mou et al., 2016</a></span>)' in html
+    assert '<dt id="mou2016" data-id="mou2016">Mou et al., 2016</dt>' in html
+    num = mdhtml2html(doc, number_headings=False, cite='numeric')
+    assert 'tasks <span class="cite">[<a href="#mou2016">1</a>]</span>.' in num
+    assert '<span class="cite"><a href="#dai2015">Dai and Le [2]</a></span> fine-tune' in num
+    assert '<span class="cite">[<a href="#dai2015">see 2</a>]</span>' in num
+    assert '<span class="cite">[<a href="#dai2015">2</a>, <a href="#long2015a">3</a>]</span>' in num
+    assert 'note <span class="cite">[<a href="#anon">4</a>]</span> agrees (<span class="cite">[<a href="#mou2016">1</a>]</span>)' in num
+    assert '<dt id="mou2016" data-id="mou2016">[1]</dt>' in num and '<dt id="anon" data-id="anon">[4]</dt>' in num
+    with pytest.raises(ValueError, match='citation'): mdhtml2html(md2mdhtml(CITATIONS.replace('[@mou2016]', '[@mou2016]{ref=page}')))
+    with pytest.raises(ValueError, match='bibliography entries'): mdhtml2html(md2mdhtml('See [@nope].'))
+    with pytest.raises(ValueError, match='cite style'): mdhtml2html(doc, cite='apa')
+    gfm = md2gfm(CITATIONS, number_headings=False)
+    assert ('tasks (Mou et al., 2016). Dai and Le (2015) fine-tune a language model, as do others (see Dai and Le, 2015) and '
+        '(Dai and Le, 2015; Long et al., 2015a). An unattributed note Anonymous agrees (Mou et al., 2016).') in gfm
+    assert '\nMou et al., 2016\n: Lili' in gfm and ':::' not in gfm
+    gnum = md2gfm(CITATIONS, number_headings=False, cite='numeric')
+    assert 'tasks [1]. Dai and Le [2] fine-tune a language model, as do others [see 2] and [2, 3]. An unattributed note [4] agrees ([1]).' in gnum
+    assert '\n[1]\n: Lili' in gnum and '\n[4]\n: An unattributed' in gnum
+    typ = mdhtml2typst(doc, number_headings=False)
+    assert '(#link(<mou2016>)[Mou et al., 2016])' in typ and '#link(<dai2015>)[Dai and Le (2015)]' in typ
+    assert '(#link(<dai2015>)[Dai and Le, 2015]; #link(<long2015a>)[Long et al., 2015a])' in typ
+    tnum = mdhtml2typst(doc, number_headings=False, cite='numeric')
+    assert '\\[#link(<mou2016>)[1]\\]' in tnum and '\\[#link(<dai2015>)[2], #link(<long2015a>)[3]\\]' in tnum
+    assert '/ #metadata(none) <mou2016>\\[1\\]: Lili' in tnum