Getting started¶

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.

Prerequisites¶

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.

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

   npmpip / uv

   npm install -g mystmd
   

   uv tool install mystmd     # or: pip install 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 plugin¶

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 layout¶

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 references¶

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.

Preview¶

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 publication¶

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 steps¶

• 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.