Citation support in the themes: a "Cite this" control driven by CITATION.cff

[mmcky]

Background

Suggestion out of a conversation with Simon Scheidegger about the Deep Learning for Solving and Estimating Dynamic Economic Models course site (itself a MyST site): our published lecture sites should hand the reader a ready-made citation — driven by a CITATION.cff in the repo, and surfaced on the site in a range of formats (BibTeX, APA, RIS, and the raw .cff).

#342 already covers adding CITATION.cff files to the book-* repos so GitHub renders its "Cite this repository" sidebar button. This issue is the other half of the same idea: what the themes do with that metadata, so a reader landing on the published site never has to go to GitHub to work out how to cite it. Scope is quantecon-theme.mystmd, quantecon-book-theme, and the upcoming book and community-lecture themes.

What exists today

mystmd (and therefore Jupyter Book ≥ 2)

Jupyter Book 2 is built on the MyST engine, so whatever mystmd offers is what JB2 offers.

Capability	Status
Generate CITATION.cff from myst.yml	Yes — a cff export target, landed in myst-cli 1.3.3 (Aug 2024) via jupyter-book/mystmd#1397
Read CITATION.cff into myst.yml	No — requested in jupyter-book/mystmd#2401 (open, Nov 2025)
Render a "cite this" affordance on the site	No — nothing citation-related in the @myst-theme packages we consume

The export is declared in project frontmatter, and myst build --cff writes the file from project (or page) frontmatter — authors, title, DOI, license, abstract — through the cffjs library. CFF fields that have no myst.yml equivalent go in the export block:

version: 1
project:
  ...
  exports:
    - format: cff
      date-released: '2026-08-20'

Two consequences worth noting. First, the direction is one-way — myst.yml is the source of truth and the .cff is a build artifact; jupyter-book/mystmd#2401 is the upstream issue to watch if we would rather make the .cff canonical and have myst.yml extend from it. Second, because the export produces a real file with an id:, it can be referenced from the site's downloads: config — so a MyST site can already offer CITATION.cff as a download with no theme change at all. That gets us the raw file, not the "pick your format" experience.

Jupyter Book 1 (Sphinx) — quantecon-book-theme

There is no CITATION.cff support anywhere in the JB1 stack. Citation support in JB1 means sphinxcontrib-bibtex — the {cite} role and a {bibliography} directive over a .bib file — which is about citing other works from within the text, not about how to cite the lecture series itself. Neither sphinx-book-theme nor pydata-sphinx-theme ships a "cite this" component.

So everything on this side is ours to build: a small Sphinx extension that reads CITATION.cff from the repo root, converts it, and exposes the result to the theme's layout.html. cffconvert (Python, CLI and importable) converts CFF to BibTeX, APA-like, RIS, EndNote, CodeMeta, Zenodo JSON and schema.org JSON. Important caveat: it does not convert the references or preferred-citation keys — which matters directly, because the files proposed in #342 lean on preferred-citation to point at the published book.

Our repos right now

None of lecture-python.myst, lecture-python-advanced.myst, lecture-jax, lecture-datascience.myst, lecture-julia.myst, quantecon-theme.mystmd or quantecon-book-theme has a CITATION.cff. QuantEcon.py does, and gets the GitHub sidebar button for free as a result.

The gap

Generation is solved on the MyST side and absent on the Sphinx side. Presentation is unsolved on both. The thing Simon actually suggested — a reader-facing control that yields a correct citation in the format they want — is theme work in both stacks, and no upstream component exists to drop in.

Proposed scope

1. quantecon-theme.mystmd — add a "Cite this" control to the project header. app/components/ProjectFrontmatter.tsx is the natural home, alongside the author list and the last-changed control. Two candidate sources: build the formats client-side from the frontmatter the theme already receives, or read a generated CITATION.cff. Frontmatter-driven is preferable — it works for every project using the theme without each repo having to ship or regenerate a file.
2. quantecon-book-theme — the equivalent control for the JB1 sites, which needs the Sphinx extension described above (CFF in, converted formats out, injected into layout.html).
3. Upcoming book theme and community-lecture theme — build the same component in from the start, as part of the theme baseline rather than a later retrofit.
4. A shared spec first — agree the fields, the formats offered, and where the control lives before either implementation starts, so the two stacks do not diverge in wording or placement.

Open questions

• Source of truth. Decided: the committed CITATION.cff is the source of truth, because it integrates with GitHub directly at the repo level and lines up with Add citation support (CITATION.cff) across book-* repositories #342. See the comment below for what that means for each stack.
• Which formats. BibTeX and APA cover most of the audience; RIS adds Zotero/Mendeley/EndNote import; the raw .cff is cheap to include. Anything beyond that is probably noise.
• What are we citing. Decided: it depends on document type. A book cites as a whole work; a lecture series is better cited per page, since readers reference an individual lecture rather than the series. So the control's behaviour is keyed off document type rather than being one fixed shape. See the comment below.
• DOIs. Worth minting Zenodo DOIs for the lecture series (as QuantEcon.py does), so the citation resolves to something permanent? That decision is upstream of the theme work.
• Machine-readable metadata. Should the same metadata also emit schema.org JSON-LD and/or Google Scholar <meta> tags, so the sites are indexable as scholarly works? Cheap to add once the data is in the theme.
• preferred-citation. If we adopt the Add citation support (CITATION.cff) across book-* repositories #342 pattern (repo metadata plus preferred-citation for the published book), the Sphinx converter needs to handle a key cffconvert skips.

Task list

• Agree the shared citation spec (formats, placement, wording) — source of truth and citation granularity now decided, see comments
• Write the CITATION.cff reader as a build-time MyST transform plugin, following plugins/git-metadata.mjs
• Write the Sphinx counterpart beside get_git_last_modified in quantecon-book-theme
• Separately, decide whether to de-duplicate authors/title out of myst.yml (upstream extends, or a local pre-build config fragment)
• Define the per-page citation composition rules for lecture series (which CFF fields carry over, what the page contributes)
• Prototype the "Cite this" control in quantecon-theme.mystmd
• Sphinx extension to read and convert CITATION.cff, plus the control in quantecon-book-theme
• Fold the component into the upcoming book and community-lecture themes as baseline
• Add CITATION.cff to the lecture repos, coordinated with Add citation support (CITATION.cff) across book-* repositories #342 for the book-* repos
• Track Extend Myst.yml from CITATION.cff jupyter-book/mystmd#2401 upstream — now a dependency rather than a nice-to-have, given the decision above

[mmcky]

Decisions

1. The committed CITATION.cff is the source of truth. It integrates with GitHub directly at the repo level — the "Cite this repository" sidebar button, Zenodo and Zotero pickup — and it makes this issue and #342 one piece of work off one file rather than two parallel metadata stores.

2. Citation granularity follows document type. A book is cited as a whole work. A lecture series is better cited per page, because readers reference an individual lecture, not the series. So the "Cite this" control is not one fixed shape — its behaviour is keyed off the document type the theme is rendering.

What decision 1 costs us on each stack

The Sphinx side gets easier and the MyST side gets harder, because mystmd's only CFF support runs the other way.

	Sphinx / quantecon-book-theme	mystmd / quantecon-theme.mystmd
Reading a committed CITATION.cff	Natural — an extension reads the repo root at build time, converts, injects into layout.html. Nothing upstream to wait on.	Not supported. myst-cli only writes CFF (myst build --cff); it cannot read one.
extend: in myst.yml	n/a	Won't help directly — extend: targets are validated as MyST config files (version: 1 plus project/site keys), so extend: CITATION.cff is not valid.
Library support	cffconvert parses and converts, but skips references and preferred-citation.	cffjs 0.1.0 exports readCFF, writeCFF, validateCFF and mystFrontmatterToCFF — parsing and validation exist, but there is no cffToMystFrontmatter. The reverse mapping is the missing piece in the library too, not just in myst-cli.

That makes jupyter-book/mystmd#2401 a real dependency rather than a nice-to-have. Three ways to close the gap, roughly in order of leverage:

1. Upstream. Contribute the reverse mapping to cffjs and the extends-from-CFF path in Extend Myst.yml from CITATION.cff jupyter-book/mystmd#2401. Highest leverage and it benefits every JB2 project, but on someone else's timeline.
2. Local pre-build step. A small script or action converts CITATION.cff into a MyST config fragment (version: 1 plus project.authors / title / doi) that myst.yml lists under extend:. Uses only features mystmd already has; cost is a generated file in the repo.
3. Theme-side, at runtime. Ship CITATION.cff as a static site asset and have the control parse and convert it in the browser. This keeps the .cff canonical, needs nothing from mystmd, and the same shape works on the Sphinx side (extension copies to _static/, control fetches it) — one implementation across both stacks.

The distinction that matters: option 3 gives us the citation control but leaves authors and title still duplicated in myst.yml for the page header. Options 1 and 2 remove the duplication as well. If we care about the duplication, 2 is the pragmatic near-term move and 1 is where it should end up.

What decision 2 means in practice

A repo-level CITATION.cff is a single record — the format has no notion of per-page entries, and one file per lecture would be an abuse of it. So per-page citation is composed by the theme, not stored: the .cff supplies the shared fields (authors, series title, publisher, year, DOI, URL) and the page supplies its own title and stable URL.

That maps onto citation types cleanly:

Document type	What the reader gets	BibTeX shape
Book (book-* repos, upcoming book theme)	One citation for the whole work, straight from preferred-citation	@book
Lecture series (lecture-*, community lectures)	A citation for the lecture they are reading, plus the series citation as a secondary option	@incollection / @inbook per page with booktitle set to the series title; @book or @misc for the series

Two consequences worth flagging early. Per-page citation needs a stable per-page URL and, if we want it to resolve permanently, a per-page identifier — which reopens the Zenodo DOI question, now specifically at page granularity rather than series granularity. And on the Sphinx side we are composing entries by hand anyway, which softens the cffconvert preferred-citation gap noted above: we need our own mapping from CFF fields to a per-page entry regardless, so the converter's limitation costs us less than it first appeared.

[mmcky]

Where the processing happens: build time, in both stacks

Yes — the conversion should run in the builder, not in the browser, and both themes already ship exactly this pattern for git metadata. That precedent is worth following closely rather than inventing something new.

quantecon-theme.mystmd ships plugins/git-metadata.mjs, a document-stage MyST transform. It runs inside myst build / myst start, shells out to git log --follow for each page, and attaches the result to the page AST as mdast.data.git_metadata. The theme then renders it in PageHeaderHistory.tsx. A citation.mjs plugin is the same shape: read CITATION.cff from the project root, parse and validate it, compose the citation, attach it to the page data, let the theme render a control from it.

quantecon-book-theme does the Python equivalent — get_git_last_modified / get_git_changelog in src/quantecon_book_theme/__init__.py, injected into the Jinja context on the html-page-context hook. A citation extension slots in beside it.

This matters because the MyST theme is a separate Remix app that only ever sees the site JSON that myst-cli produced — it has no access to the repo working tree at render time. So a plugin is not just the tidier option, it is what makes a repo-root CITATION.cff reachable at all without either upstream jupyter-book/mystmd#2401 or a runtime fetch of a static asset. It also keeps ajv and js-yaml out of the client bundle, and the citation renders with JavaScript disabled.

This supersedes option 3 in the previous comment: rather than shipping the .cff as a static asset and parsing it in the browser, the plugin does the read at build time. Options 1 and 2 remain the answer to the separate problem of authors and title still being duplicated in myst.yml for the page header — the plugin powers the citation control, it does not de-duplicate the frontmatter.

Two constraints worth knowing up front

Transform plugins receive no options. myst-cli does not pass configuration to transform plugins — git-metadata.mjs documents this and uses an environment variable (QE_GIT_METADATA_MAX) instead. So the citation plugin cannot be handed a "this is a book" / "this is a lecture series" flag through myst.yml in the obvious way.

Which suggests reading the document type out of the CFF itself, and it falls out naturally: a book repo carries preferred-citation with type: book, so the control renders one whole-work citation; a lecture series has no book-typed preferred-citation, so the control composes a per-page entry with the series as booktitle. No extra configuration, no environment variable, and the type decision lives in the same file that is already the source of truth. Worth validating against real files before committing to it.

One implementation note for whoever picks this up: the git plugin reads per page because git history is per page. The .cff read is per project, so it should be memoised across pages rather than re-read and re-validated for every file in the build.