Block embeds — the `{astra}` directive¶

The {astra} directive embeds any addressable element, child, or collection as a block. The path decides what is rendered; the directive makes no styling decisions of its own, so the result is clean on the stock book-theme and richer under a dedicated theme.

:::{astra} decisions.algorithm
:::

What each path renders¶

Path	Renders
`decisions.<id>`	The decision: label, rationale, and its options as tabs, with the universe's selection marked
`decisions.<id>.<option>`	One option: label, description, supporting insights
`outputs.<id>`	The active output — a real figure, table, or metric when materialized
`findings.<id>`	The finding: claim + notes + scope + evidence
`findings.<id>.<evidence>`	One evidence record
`prior_insights.<id>`	The prior insight as a "see also" admonition with its evidence
`inputs.<id>`	The input as a one-row registry table
`<sub-analysis>`	A neutral summary card for the sub-analysis
`inputs`, `outputs`, `decisions`, `findings`, `prior_insights`, `analyses`	The whole collection — a registry

Examples:

:::{astra} outputs.hubble_diagram
:::                                   # the figure (or table / metric)

:::{astra} findings.signal_detected
:::                                   # claim + notes + scope + evidence

:::{astra} reconstruction
:::                                   # a sub-analysis summary card

:::{astra} outputs
:::                                   # a whole collection → the outputs registry

:::{astra} reconstruction.inputs
:::                                   # the inputs registry for a sub-analysis

A bare sub-analysis target still renders a summary card. It does not guess a page URL: site navigation belongs to MyST's table of contents. An inline sub-analysis reference can expose a link when exactly one concrete TOC page is mapped to that analysis; see multi-page reports.

Universe files still select decisions, conditional records, and artifact bindings for the entire rendered publication. They are resolution inputs, rather than records or collections, so universes and universes.<id> are not addressable {astra} paths. The rendered decisions and outputs already reflect the selected universe; see project root and universe.

Options¶

Options follow MyST's :key: value form:

Option	Meaning
`:label:`	Cross-reference label for the rendered block. This replaces the default `<kind>-<id>` anchor — manage the anchor yourself if you set it.
`:caption:`	Caption text (figure / table outputs). Markdown is allowed.
`:compact:`	Findings: claim + notes + scope only (no evidence).
`:show:`	Findings: parts to include, from `claim, notes, scope, evidence` (comma- or space-separated). The claim is always kept.
`:hide:`	Findings: parts to exclude (same part names).
`:class:`	Extra CSS class(es) on the rendered block.

:::{astra} outputs.bao_fit_plot
:caption: The post-reconstruction fit; see {astra}`decisions.algorithm`.
:label: fig-bao
:::

:::{astra} findings.bao_detected
:hide: evidence, scope
:::

Cross-referencing an embedded block¶

Use the directive's :label: option and MyST's standard {ref} role for project-wide cross-references. Figures and tables are numbered by MyST as usual:

:::{astra} outputs.hubble_diagram
:label: fig-hubble
:::

{ref}`fig-hubble`

Markdown inside ASTRA fields¶

Descriptions, rationales, finding notes, and other ASTRA prose fields support normal MyST structure, inline markup, math, directives such as admonitions, and HTML. Features that require MyST's earlier host session — {mdast}, {include}, {raw}, {code-cell}, and {eval} — must instead be authored on the report page. The plugin reports an error if one appears inside an ASTRA field, so strict builds cannot silently publish unresolved content.

Errors¶

A directive whose path cannot be resolved (unknown id, wrong scope, or an inactive conditional record) renders an error admonition in place, naming the path and the reason — the rest of the page builds normally.

Block embeds — the {astra} directive¶