QuantEcon / QuantEcon/quantecon-plugins.mystmd
Move git-metadata into the shared plugins repo as a standalone plugin (quantecon-plugins.mystmd)
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 0
- Forks
- 0
- Avg merge
- 2h 52m
- Merged PRs (30d)
- 7
Description
Context. Decision D8 of the report/compliance theme planning (2026-09-02): plugins/git-metadata.mjs stays in quantecon-theme.mystmd for now, and this issue captures the idea of turning it into a standalone plugin in this repository. The QuantEcon/quantecon-theme.mystmd#93 Q2 decision kept the plugin in the lecture theme because it was the only plugin and is theme-coupled, and said a shared plugins repo would be revisited only if a second, non-theme-coupled plugin appeared. That trigger has now fired: the report theme work creates a generic, portable-AST data-presentation plugin family that lives in this repository, with the compliance-specific wrappers living beside the report theme.
What "standalone" means here
- Publish the transform as a single-file bundle attached to a tagged release of this repository (the remote-plugin form the mystmd docs show), instead of the raw tag URL in the lecture theme.
- Document the data contract it emits,
mdast.data.git_metadatawithlast_modifiedand achangeloglist of{hash, short_hash, author, date, message}, so any theme can render it rather than only the lecture theme'sapp/components/PageHeaderHistory.tsx. The report theme will render the same data as a "Last changed" line in its footer. - Keep configuration as it is (the
QE_GIT_METADATA_MAXenvironment variable), because transform plugins receive no options from myst-cli; record that limitation in the contract. - Repoint lecture repos'
project.pluginsURL at a quiet moment after the lecture cutover. The existing raw tag URL keeps working for anything already pinned to it.
The lecture theme's side. Repointing its visual fixture at the release asset, confirming app/components/PageHeaderHistory.tsx still renders the same data, and removing plugins/git-metadata.mjs are tracked separately as QuantEcon/quantecon-theme.mystmd#157, which is blocked on this repository shipping a release carrying the bundle.
Not blocking anything. Deliberately kept off the lecture theme's cutover tracker, QuantEcon/quantecon-theme.mystmd#147. Related: the git-metadata entry in the lecture theme's UPSTREAM-CANDIDATES.yml and the upstream request jupyter-book/mystmd#2213, both of which this move would make easier to pursue.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the existing plugins/git-metadata.mjs implementation and the contract described here, including mdast.data.git_metadata and QE_GIT_METADATA_MAX. Define the release asset and documentation so themes can consume the data, then verify that the tagged bundle preserves the data rendered by app/components/PageHeaderHistory.tsx; lecture-theme repointing is tracked separately in #157.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript
- Domain
- documentation, tooling
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 55/100