Skip to content

Citations and bibliographies - #81

Closed
jackhogan wants to merge 3 commits into
mainfrom
citations
Closed

jackhogan wants to merge 3 commits into
mainfrom
citations

Conversation

@jackhogan

Copy link
Copy Markdown

Adds support for:

  • bibliographies: a definition list inside ::: {.bibliography}, where each term is a citation label, and its id is the citation key.
  • citations: using [@key] syntax with optional prefix/suffix text; supports numeric [1] and author-year (Howard and Ruder, 2018) rendering across all export formats.

E.g.:

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*.
:::

The following table shows the various citation forms, and how each renders in the two styles:

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]

Author-year is the default; using cite_style: numeric in frontmatter, or cite_style='numeric' on bake, mdhtml2html, mdhtml2gfm, mdhtml2typst, md2html and viewmd selects numeric style, which numbers entries in bibliography order.

Apply the same definition list merging logic that occurs at the top level to blocks within containers.
- `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`.
@jackhogan
jackhogan requested a review from jph00 October 29, 2026 16:11
@jackhogan jackhogan self-assigned this Oct 29, 2026
@jackhogan jackhogan added the enhancement New feature or request label Oct 29, 2026
@jph00

jph00 commented Oct 30, 2026

Copy link
Copy Markdown
Contributor

Thanks @jackhogan - implemented a slightly different design. Take a look - hope it's ok! :)

@jph00 jph00 closed this Oct 30, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants