Plugin families for the mystmd engine (the JavaScript myst CLI that Jupyter Book ≥ 2
is built on), published as single-file .mjs bundles attached to GitHub Releases and
registered by URL from a project's myst.yml. The .mystmd suffix marks the repository
as engine tooling, in the same family as
quantecon-theme.mystmd and
quantecon-theme-report.mystmd.
Planning complete (2026-09-02); build not started. Work hangs off the Project-typed
tracker #2; its sub-issues
are the contract, the toolchain, the two directive groups and the first release. Whether the
family is later extracted to a general project or proposed upstream is held in
#8. The first consumer is
the report theme,
quantecon-theme-report.mystmd#2. The plan that created this repository is
PLAN.md in the report theme's design handover.
| Family | Bundle | Contents | Status |
|---|---|---|---|
| Data presentation | datavis.mjs |
stats, bar-list, stacked-bar, heatmap, data-table, chips, badges, delta-list — data-presentation directives reading inline data or CSV files |
planned first |
| Repository metadata | git-metadata.mjs |
per-page git history (last modified + changelog) | lives in the lecture theme today; the move is tracked in #11 |
Domain-specific wrappers that apply a rubric to a particular dataset (for example the
compliance ledger's qe-* directives) do not live here; they ship beside the theme
that renders them and emit the same node shapes these families define.
- Portable AST. Every directive emits standard MyST nodes — classed
div/span, tables and lists — with structured data as node properties and a small set of tone hints, and with children that are a genuine plain rendering of the same data. Content renders in any theme and survives PDF export; a theme may upgrade the nodes by implementingCONTRACT.mdand the schemas inschema/. The coregridandcardnodes are deliberately not used:myst-to-texhas no handler for them and silently drops the whole subtree from a LaTeX export. - Self-contained bundles. A remotely loaded plugin cannot import npm packages or other bundles, so each family is bundled to one file using Node built-ins only.
- One registration per family. mystmd keeps the first directive registered under a
name and warns on duplicates, and core registers before any plugin, so a plugin claiming a
core name is ignored with no error at all. A family is loaded exactly once per project;
names stay plain nouns with a documented
dv-alias fallback, and the test suite re-checks every name against the engine on each run. - Share the contract, not the code. Consumers emitting the same nodes duplicate a few helpers rather than depending on this repository at build time.
Pin a release asset in project.plugins:
project:
plugins:
- https://github.com/QuantEcon/quantecon-plugins.mystmd/releases/download/vX.Y.Z/datavis.mjsMIT — see LICENSE.