Feature request: structured "Related literature" metadata rendered by the themes (quantecon-book-theme + quantecon-theme.mystmd)

[mmcky]

Motivation

Several lectures open with an ad-hoc note explaining which paper the lecture is based on, e.g. (from a recent mobility lecture):

Note
This lecture draws heavily on the first few sections of the paper "Mobility" by Daniel Carroll, Nicholas Hoffman and Eric R. Young [Carroll et al., 2026].
That paper collects the standard mobility measures in one place, applies them to US wealth data, and then asks whether workhorse macroeconomic models can reproduce what it finds.

This is useful information, but today each author hand-writes it as a generic {note} admonition, so placement, wording and styling vary across lectures and series. It would be better to treat "supporting / related literature" as structured lecture metadata that the theme renders in a consistent place and style.

Proposal

Let a lecture declare its related literature as metadata, and have the theme render it as a dedicated "Related literature" admonition (or card) with consistent placement.

Sketch of the data model (per entry): a citation key (resolved against the project bib so it gets a proper hyperlinked citation), an optional direct URL/DOI, and a free-text note explaining the relationship ("draws heavily on the first few sections of ...").

Example of what an author would write in the lecture frontmatter:

related_literature:
  - cite: carroll2026mobility
    note: >
      This lecture draws heavily on the first few sections of this paper, which
      collects the standard mobility measures in one place, applies them to US
      wealth data, and asks whether workhorse macro models can reproduce what it finds.

Rendered output: a Related literature admonition with a book/paper icon, one item per entry, with the citation rendered via the normal citation machinery (so it also lands in the References section).

Where should this live?

Two stacks to cover, and in both cases the work probably splits into (a) a parser/extension that reads the metadata and emits an admonition node, and (b) theme styling/placement.

Stack	Parsing	Rendering
Sphinx / Jupyter Book 1 (quantecon-book-theme)	New small extension (working name sphinx-related-literature, alongside sphinx-exercise / sphinx-proof) that reads the frontmatter key and injects an admonition node; could alternatively be a directive {related-literature} as a first step	quantecon-book-theme CSS + icon for the new admonition class
MyST-MD (quantecon-theme.mystmd)	A MyST plugin (transform) that reads parts.related_literature / a frontmatter key and produces an admonition, or rely on mystmd's native document parts and let the theme render the part directly	quantecon-theme.mystmd renders the part in a fixed location

Open question for discussion: should the source of truth be frontmatter (structured, machine-readable) or a document part (prose block, author-friendly)? A hybrid is possible: frontmatter for the citation key(s), a part for the explanatory prose.

Does mystmd support "footer" metadata?

Not as a second YAML block at the bottom of the file — frontmatter is top-only in both Sphinx/MyST-NB and mystmd. But mystmd's document parts give us what we actually want (keep the header from growing and crowding out content):

• A part can be declared as a content block anywhere in the document — +++ {"part": "related_literature"} followed by normal markdown — or as a cell tag in a notebook, not only in frontmatter.
• Custom part names are allowed; known parts include abstract, acknowledgments, data_availability, etc. A custom related_literature part is legitimate.
• The theme decides where the part is rendered, so placement is consistent regardless of where the author wrote it.
• Site-level footer/banner parts also exist (via site.parts in myst.yml), but those are site-wide, not per-lecture, so they are not the right fit here.

So for mystmd the cleanest design is a related_literature part (prose at the end of the source file, rendered by the theme near the top or wherever we decide). For Sphinx there is no equivalent built-in, so the extension would need to read either frontmatter or a directive.

Placement

Options, to be decided: (1) directly under the title / before the Overview, matching where authors currently put the note; (2) at the end, just before References; (3) in the sidebar / page metadata panel. Option (1) matches current practice; option (3) would be the least intrusive to the reading flow.

Tasks

• Agree on data model (frontmatter key vs document part vs hybrid) and placement
• Sphinx: prototype sphinx-related-literature (or a directive in an existing extension) and styling in quantecon-book-theme
• MyST-MD: render a related_literature part in quantecon-theme.mystmd (plugin if a transform is needed)
• Add guidance to the lecture style guide / manual
• Migrate existing hand-written "this lecture is based on ..." notes once available

Related repos: QuantEcon/quantecon-book-theme, QuantEcon/quantecon-theme.mystmd, QuantEcon/sphinx-exercise, QuantEcon/sphinx-proof (as precedents for small Sphinx extensions).