astra-theme

Rich MyST web themes for ASTRA publications, in two flavors built on myst-theme 1.3.1:

• article (themes/article): a single scrolling publication;
• book (themes/book): multi-page, with navigation and search.

Both share one ASTRA overlay (packages/astra). Content that does not use ASTRA renders exactly as in the stock MyST themes.

Usage

Pair the theme with the MySTRA plugin in myst.yml:

site:
  template: https://github.com/LightconeResearch/astra-article-theme.git
  # or https://github.com/LightconeResearch/astra-book-theme.git

Keep the .git suffix: MyST reads any other non-zip URL as a template-index link. This form tracks the latest release, but MyST downloads the template once into _build/templates/ and reuses it; run myst clean --templates to pick up a newer release.

Pinning a version

Every release is tagged in the published repos (see the article tags or the book tags). To stay on one, point site.template at that tag's zip archive:

site:
  template: https://github.com/LightconeResearch/astra-article-theme/archive/refs/tags/v0.0.15.zip

A pinned build is reproducible and never changes under you. To upgrade, edit the tag; the new URL is downloaded on the next build.

What it adds

MySTRA resolves the ASTRA project at build time and embeds a versioned publication bundle in the MyST output. The theme validates that bundle with @astra-spec/sdk and adds:

• inline references, hover previews and record dialogs from @astra-spec/ui;
• an ASTRA Inventory view of the page's analysis, also reachable at #astra-inventory;
• in-place reading of cited arXiv papers (DOIs 10.48550/arXiv.<id>) with pdf.js, falling back to the DOI link;
• Lightcone styling from @lightcone-research/brand.

If the bundle is missing or invalid, the plain MyST content still renders. @astra-spec/ui and the brand package are pinned to exact versions because the JupyterLab and VS Code hosts share the same rendering contract.

Development

Requires Node.js 20+.

npm ci
npm test
npm run typecheck
npm run build        # or build:article / build:book

Releasing: push a vX.Y.Z tag. CI builds both themes, publishes them to the deploy repos above, attaches zips to a GitHub Release and bumps the version on main (see .github/workflows/publish-theme.yml).

License

BSD 3-Clause for the ASTRA overlay and repository configuration; the vendored MyST app shells remain MIT. See NOTICE.