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, a universe in universes/ (its decision selections drive the report), and (for figures/tables/values) materialised results in results/. New to ASTRA? Start with the ASTRA getting-started guide first.

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

   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>/<output-id>.png   Materialised result artifacts
├── myst.yml            Registers the plugin; lists pages
└── index.md            Your report (+ optional sub-analysis pages)

MySTRA never scans the results tree: it computes each output's directory deterministically from the convention above (the analysis's path: + universe + output id) and resolves the artifact file lazily, as it renders. A sub-analysis that declares path: ./analyses/<sub> roots its own results/<universe>/ there.

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 resolves the first universe in universes/.

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 and the resolved store the plugin emits.