`nb-exec-table`: an execution-statistics directive reading the fork's per-notebook records, as a project-stage plugin

What the lectures publish

Every QuantEcon lecture series has a status.md whose whole content is {nb-exec-table}: MyST-NB's table of which notebooks executed, when, by what method (cache hit or run), how long each took and whether it succeeded — the standing build-health page a maintainer opens after a publish (for example https://python-programming.quantecon.org/status.html). One page per repository, 18 repositories. On the mystmd fork the directive is unknown, and lecture-wasm's status page shows a red Unknown Directive callout today.

Decision (2026-09-17, mmcky; QuantEcon/mystmd#76)

Split core and extension:

• Core, in QuantEcon/mystmd (upstream candidate): the execution pass records per-notebook stats — path, mtime, method, runtime, success — into the session store and writes them to _build/site/execution.json. That is the only part that needs engine access.
• Extension, this repository: the nb-exec-table directive and a stage: 'project' transform that reads the records and emits an ordinary MyST table node, so it inherits whichever theme's table styling. The directive keeps MyST-NB's name, so the 18 status.md pages need no edit.

Why a plugin

Plugins declare transforms with stage: 'document' | 'project' (packages/myst-common/src/types.ts L121–L124 in the fork), and project-stage transforms run in myst-cli's mdast.ts after every page has been processed and executed. That is exactly the ordering the table needs: the status page can sit anywhere in the TOC and still be filled after all notebooks have run. Keeping the rendering here also keeps fork core minimal and uses this family's existing release pipeline and project.plugins URL model.

Proposed change

1. A directive nb-exec-table (no arguments; optional :sort: by name, runtime or status) that emits a placeholder node.
2. A project-stage transform that reads _build/site/execution.json (path from the session's build directory), replaces each placeholder with a table node — columns Document, Modified, Method, Run Time (s), Status — and, when the file is absent (a build without --execute), replaces it with a short admonition saying execution statistics are not available for this build, never an error or an empty table.
3. Tests: a fixture project with three notebooks (one cached, one executed, one failed) produces the expected table; the no-execute case produces the note; a second myst build is idempotent.
4. Docs: a page in this family's docs; QuantEcon.manual's status-page guidance points at it.

Cautions

• QuantEcon/mystmd#101: a plugin that fails to load leaves --strict at exit 0, so a bad pin would silently bring back a callout on every status page. The fork fix there rises in priority once a reader-facing page depends on a plugin; until then the theme-parity harness's rendered checks (QuantEcon/project-theme-parity#15) assert the table is drawn.
• If upstream later wants the directive in core, it moves with no source change; the records format in execution.json is the contract to keep stable.

Acceptance criteria

• With the fork's execution.json present, {nb-exec-table} renders one row per executed notebook with the five columns above.
• Without --execute, it renders the "not available" note and no error.
• The plugin loads from a pinned release URL in project.plugins, and myst build --strict exits 0 with the table present.
• test-lecture-theme-mystmd's status.md renders the table on its live site, and the harness's rendered.csv marks the site-feature row drawn.

Blocked by the core half, QuantEcon/mystmd#76 (the records format). Tracked from QuantEcon/project-theme-parity#12 (upstream index) and #9 (routing).

First read the plugin stage declarations in packages/myst-common/src/types.ts and the project-stage processing in myst-cli's mdast.ts, then confirm the execution.json contract in QuantEcon/mystmd#76. Use a fixture project to cover cached, executed, failed, and no-execute cases, including a second build. Done means the pinned plugin renders the table, strict builds pass, and the lecture theme and harness show it as drawn.