Authoring overview
Reference any part of an ASTRA analysis with a path, inline with the {astra} role or as a block with the {astra} directive.
You reference any part of an ASTRA analysis with one idea: a path
that mirrors astra.yaml. One name — astra — drives both surfaces, the MyST way (just as {math}
is both a role and a directive): wrap a path in the {astra} role to mention it inline, or use the
{astra} directive to embed it as a block.
Everything else — prose, math, figures you author yourself, the table of contents, multi-page structure — is ordinary MyST. If you have never written MyST Markdown before, skim the MyST authoring guide first; MySTRA adds vocabulary, it doesn't change the language.
Choosing a surface
| I want to… | Use | Example |
|---|---|---|
| Mention an element in a sentence | {astra} role | {astra}`decisions.algorithm` |
| Refer to a placed figure by number | Explicit :label: + MyST {ref} | {ref}`fig-hubble` |
| Cite the literature behind an insight | {astra:cite} / {astra:cite:t} | {astra:cite}`prior_insights.recon` |
| Put a measured number in prose | {astra:value} | {astra:value col=alpha pm=true}`outputs.table` |
| Embed a figure, decision, finding, … as a block | {astra} directive | :::{astra} outputs.hubble_diagram |
| Link to a placed block | its explicit :label: | {ref}`fig-hubble` |
| Split the report along sub-analyses | Multi-page reports | reconstruction.md |
The golden rule
Never hard-type a measured number, restate a decision, or re-describe an output. If it exists in
astra.yaml or in a result product, reference it. The whole point of MySTRA is that the report
cannot drift out of sync with the analysis — every restated fact is a place where it can.
A complete miniature report
# BAO from the ELG sample
## Method
We adopt the {astra}`decisions.algorithm` for density-field reconstruction;
the {astra}`decisions.algorithm.multigrid` option follows
{astra:cite:t}`prior_insights.recon_sharpens_bao`.
:::{astra} decisions.algorithm
:::
## Results
The fit yields $\alpha =$ {astra:value col=alpha where="tracer=elg1" pm=true}`outputs.alpha_table`
({ref}`fig-bao`).
:::{astra} outputs.bao_fit_plot
:caption: Correlation function and best-fit model, post-reconstruction.
:label: fig-bao
:::
## Findings
:::{astra} findings
:::