Quick Start

This walk-through takes you from an existing ASTRA project to a live, self-updating report in about five minutes. You will install the MyST CLI, register the plugin, write your first references, and preview the site.

If you'd rather see the authoring vocabulary first, jump to the authoring guide.

PrerequisitesCopy Anchor Link

MySTRA renders reports on top of an ASTRA analysis, so you need:

1. An ASTRA project — a directory with an astra.yaml, optionally one or more universe files in universes/, and (for figures/tables/values) materialised results in results/. Without a universe file, the SDK uses the decisions' authored defaults. New to ASTRA? Start with the ASTRA getting-started guide first, or read ASTRA for how the Lightcone Stack uses it.

2. The MyST CLI (mystmd), which needs Node ≥ 20:

   npm

   pip / uv

   Copy Text

   npm install -g mystmd

   Verify with myst --version.

There is nothing to install for MySTRA itself: MyST loads a plugin from a single bundled .mjs file referenced by URL.

Register the pluginCopy Anchor Link

In your ASTRA project directory, create a myst.yml that points at the latest release artifact and lists your pages:

version: 1
project:
  plugins:
    - https://github.com/LightconeResearch/MySTRA/releases/latest/download/mystra.mjs
  toc:
    - file: index.md
site:
  template: book-theme

The …/releases/latest/download/… URL always tracks the newest release; MyST fetches and caches the file on the first build.

- https://github.com/LightconeResearch/MySTRA/releases/download/v0.0.1/mystra.mjs

Project layoutCopy Anchor Link

MySTRA expects the standard ASTRA conventions:

my-analysis/
├── astra.yaml          Analysis specification (decisions, findings, outputs, …)
├── universes/
│   └── baseline.yaml   Decision selections for the baseline universe
├── results/
│   └── baseline/<output-id>.png               Materialised result artifacts
├── myst.yml            Registers the plugin; lists pages
└── index.md            Your report (+ optional sub-analysis pages)

Write your first referencesCopy Anchor Link

Create an index.md and reference the analysis instead of restating it. Everything is addressed by a path that mirrors astra.yaml:

# My analysis report

We adopt the {astra}`decisions.fit_method` and find
{astra:value col=slope sig=3}`outputs.fit_params`
for the slope of the relation.

:::{astra} outputs.fit_params
:::

:::{astra} decisions.fit_method
:::

Three surfaces, one vocabulary:

• the {astra} role mentions an element inline — inline references;
• the {astra} directive embeds it as a block — block embeds;
• the {astra:value} role interpolates a live number — live values.

Everything else — prose, math, figures you author yourself, the table of contents, multi-page structure — is ordinary MyST.

PreviewCopy Anchor Link

Run the stock MyST CLI from the project directory:

myst start        # → http://localhost:3000

That's it — no custom server and no build step of your own. MySTRA reads astra.yaml from the working directory and delegates full validation, universe selection, and resolution to the SDK. With multiple universe files, the SDK selects the first .yaml or .yml filename in lexical order; with none, it uses authored defaults.

Build for publicationCopy Anchor Link

myst build --html

produces a static site in _build/html/ that you can host anywhere. All referenced result artifacts are copied and hashed by MyST's asset pipeline; the output is fully self-contained.

Next stepsCopy Anchor Link

• Learn the full path grammar — one idea that drives every surface.
• Split a large report into multiple pages that mirror your sub-analyses.
• Building a theme? See theming for the classes, canonical paths, and SDK publication bundle the plugin emits.