Skip to content

Multi-page reports

A report can mirror the analysis tree: one page for the root analysis, and one page per sub-analysis. Pages are ordinary MyST pages — you list them in myst.yml's toc: — and MySTRA maps each page to an ASTRA scope that determines which elements the page's resolved store contains.

The dotted-filename convention

A page's scope is derived from its file name: each .-separated segment is one analysis level.

File Scope
index.md The root analysis
reconstruction.md The reconstruction sub-analysis
reconstruction.features.md features inside reconstruction
myst.yml
version: 1
project:
  plugins:
    - https://github.com/LightconeResearch/MySTRA/releases/latest/download/mystra.mjs
  toc:
    - file: index.md
    - file: reconstruction.md
    - file: reconstruction.features.md

Overriding the scope

A page whose name doesn't follow the convention can declare its scope explicitly with the astra_scope frontmatter key — either dotted or as a list:

---
astra_scope: reconstruction.features
---

# Feature extraction

---
astra_scope:
  - reconstruction
  - features
---

A page that maps to no valid scope (e.g. an appendix about something else entirely) simply gets no ASTRA scope: roles and directives still work — they resolve from the root — but the per-page store is skipped.

What the scope changes — and what it doesn't

  • Roles and directives always resolve from the root analysis, on every page. {astra}`reconstruction.outputs.xi` means the same thing everywhere.
  • The scope only selects the page's resolved store — which elements a rich theme can join against on that page.
  • Cross-page links work through plain MyST anchors: every placed block carries a <kind>-<id> identifier, and MyST resolves [](#output-xi) project-wide to whichever page embeds it.

Embed a sub-analysis by its bare path to get a navigation card linking to its page, or embed the whole analyses registry for one card per sub-analysis:

:::{astra} reconstruction
:::

:::{astra} analyses
:::

Results for sub-analyses

A sub-analysis that declares path: ./analyses/<sub> in astra.yaml roots its own results/<universe>/ tree there; MySTRA resolves each scope's artifacts from the right base automatically. Nothing to configure on the report side.