Automathics Markup Language (atmx)¶

.atmxs files¶

.atmxs files are human-readable YAML snapshots that freeze the questions and answers generated for a particular document run. Instead of producing HTML directly, automath can write an .atmxs file (see Creating .atmxs files); you can then archive it, edit it by hand, and render it back to HTML at any time with automath render html. These are the same snapshots that automathon produces and assembles.

Top-level keys¶

A snapshot is a YAML mapping. The keys relevant at the top level are:

Key	Meaning
`preset`	the document type — `grid` or `slideshow` (required)
`title`	optional document title — the heading of a `grid`, the browser-tab name of a `slideshow`
`title_prefix`	optional, `slideshow` only; heads the browser-tab name, before the title or the file name (see Using HTML slideshows)
`rotate`	optional integer; rotates a slice of the questions (added by `--rotate`)
`font_mode`	optional `embedded` \| `served` \| `local` — the font-delivery mode to use when this snapshot is rendered to HTML
`questions`	the list of frozen question/answer entries

font_mode is the persisted delivery choice. It is written only when render atmxs --font-mode … (or automathon) stamps it; otherwise it is absent. At render time the effective mode follows this precedence — the render html --font-mode option overrides the snapshot's font_mode, which overrides the fonts.mode config default (shipped as embedded). So re-rendering a stamped snapshot reproduces the mode it was produced with, without re-passing --font-mode.

Font delivery modes¶

The same fonts can be carried into the produced HTML three ways, controlled by font_mode / --font-mode / fonts.mode (in precedence order):

Mode	What the page contains	Trade-off
`embedded`	the woff2 inlined as a base64 data URI	self-contained, works anywhere with no server; larger pages
`served`	an `@font-face` pointing at `fonts.served_base_url` (an absolute URL the operator hosts)	small pages, but needs the server and a licence that allows serving
`local`	only the font family name	small pages, but the font must be installed on the viewing machine

A small grid page is roughly 355 KB embedded versus ~11 KB served/local. A user-uploaded font (whose licence is unverified) is always forced to local, whatever was requested — it is never embedded or served. Every produced page also carries a small badge reporting whether its fonts loaded as intended — see the font badge.

AML¶

AML is the inline markup language used to write mathematical content in .atmxs files. It has two layers:

atmxg (Automathics Graphics Language) is the graphical subset of AML. It is used wherever an expression must be rendered as an SVG image: inside question and answer fields, and with the automath render svg command. Keywords: math{}, frac{}, angle{}, unit{}, table{}, barmodel{}, barchart{}, rect{}, poly{}, grid{}, axis{}, stack{}, text{} and ^{}. See the atmxg page for details.
AML (full atmx) extends atmxg with document-level elements: Q{} renders a blank placeholder (a red question mark), note{} renders a side note, and pic{} inserts an external image. The AML parser outputs HTML, embedding inline SVG for the elements that need a graphical rendering (the atmxg subset).

Answer placeholders `Q{}` and `A{}`¶

Q{} marks where the answer goes. It renders as a red question mark and works in two places:

In HTML text (e.g. 8 × 4 = Q{}) it becomes an HTML ?.
Inside an atmxg expression (e.g. table{… | bubble=×Q{}} or math{2 × Q{}}) it is baked into the SVG as a red ?, looking identical to the HTML one.

With answer_layout: inline (see below), the correction slide replaces the Q{} with the answer in green — including when the Q{} sits inside an SVG, where the whole expression is re-rendered with the answer in place of the ?.

A{} is a silent answer placeholder: it shows nothing on the question slide and is replaced by the (green) answer on the correction, whatever the answer_layout. It is handy with stack{} to drop the answer on its own line below a caption, e.g. stack{text{Prix moyen\nd'un ticket ?} ; A{}} beside a chart (see atmxg for stack{}).

External images `pic{}`¶

pic{} inserts an external image (an <img>) — handy when you need a picture that no atmxg keyword can draw yet. It is used at the same level as Q{} / A{} (in a wording or answer field), not inside an atmxg expression.

pic{filename}
pic{filename | width=200; height=120; include=true}

filename — the image file, resolved next to the .atmxs file being rendered (so it ships alongside it). Supported types: svg, png, jpg, jpeg, gif, webp.
width=, height= — CSS lengths controlling the displayed size. A bare number means pixels (width=200 → 200px); any CSS unit is accepted (width=15vw, height=4cm, width=30%). Give only one to scale the other in proportion (the aspect ratio is kept); give both to force a size. vw is convenient in slideshows so the image scales with the slide.
include= — true makes the HTML self-contained: an SVG is embedded as raw <svg> markup (its XML prolog / DOCTYPE are dropped), a raster image (png/jpg/…) is embedded as a base64 data URI. false references the image by its relative file name (the file must then ship next to the .html). Omitted, it defaults to rendering.slideshow.include_pictures (see the Configuration page; shipped default: false).

In a slideshow, an embedded SVG is stored only once (as an SVG <symbol> in a hidden block) and each occurrence becomes a tiny <use> reference — so reusing the same figure (e.g. on a question slide, on the recap shown before its correction, and on the correction itself) does not multiply its weight, and the single definition also avoids internal id collisions. This requires the SVG to have a viewBox (or a width+height from which one can be derived); otherwise it falls back to a full inline copy.

- q: 'Que vois-tu ? pic{schema.svg | width=20vw}'
  a: 'Un triangle.'

Line breaks¶

A line break in a wording (or any AML text) produces a <br>. Use either a real newline — most naturally a YAML block scalar (|) — or the literal two-character sequence \n:

- q: |
    First line.
    Second line.
  a: …
- q: 'First line.\nSecond line.'
  a: …

(Inside atmxg titles, \n is likewise the line-break convention.)

To control the spacing between lines, use one \n per line and adjust the line_height option (or the rendering.slideshow.line_height default) rather than stacking two \n — see the options table below.

A figure sharing a slide with its wording is parted from it on its own, above or below: line_height governs the lines of prose, and a drawing set against one of them would read as its caption. Leave line_height for the prose, and lower it only where the figure is the last line and there is a single line of wording above it.

Grid question fields¶

Each entry under questions: in a grid .atmxs file is a mapping:

Key	Meaning
`q`	The wording (AML markup; may contain `Q{}`, `note{}`, `pic{}`, atmxg expressions).
`a`	The answer (AML markup).
`answer_unit`	The unit the answer is expected in, e.g. `unit{cm^2}` — one AML expression. Optional, and written only by the question types that ask for a measure.
`answer_frame`	The notation the answer is written inside, as a pair of AML expressions: `["text{M(}", "text{)}"]`. Optional, and written only by the question types whose answer is named rather than merely given.

answer_unit is rendered inside the answer box, beside what the box holds: against its right edge on a question sheet and on a mail-merge template, where the room left of it is what the pupil writes the number in; right after the result on the answer key, so that it reads 28 cm². It says what the answer is to be counted in — an area asked in cm² is not the same question as one asked in m² — which is why it belongs to the question and not to the answer, and why the answer itself stays a bare number.

answer_frame is rendered around what the box holds, its two halves on either side. Where the abscissa of a point is asked for, the box is framed by M( and ): the pupil types the number alone, yet reads the notation the result is written in, and the answer key spells it out — M(12/5). On a question sheet the two halves are drawn apart, the room between them being where the answer goes (they close up around the input field of an interactive page, which is that room); on the answer key they close up around the result.

A slide has no box, so a slideshow entry has neither field: a question type that answers on a slide writes the unit — or the notation — into its a field.

Slideshow question fields and options¶

Each entry under questions: in a slideshow .atmxs file is a mapping:

Key	Meaning
`q`	The wording (AML markup; may contain `Q{}`, `note{}`, `pic{}`, atmxg expressions).
`a`	The answer (AML markup).
`duration`	Seconds the question is shown (default 20).
`answer_layout`	`below` (default), `side`, or `inline` (replaces a single `Q{}` with the answer).
`answer_extra`	Extra answer line (same green and size) shown below the answer on the correction slide, e.g. `(ou 0,25)`.
`steps`	The members of the detailed answer, from the expression asked to the result — one list entry per member, each of them AML markup. Written by `render atmxs` for the question types that have steps; it puts the Steps button on the correction slide (see slideshows). Nothing is shown until that button is pressed.
`steps_alt`	A second calculation reaching the same result — same shape as `steps`, one list entry per member — shown as its own chain beside the first behind the same button (stacked under it when the panel is too narrow). Written by the question types whose result is reached two ways, both of them taught: `perimeter_rectangle` is `(L + l) × 2` as much as it is `L × 2 + l × 2`. Only meaningful alongside `steps`.
`steps_words`	The rule the calculation applies, said in a sentence — one AML string, shown under the chains behind the same button, never beside them: a sentence wraps, where a chain broken by wrapping is unreadable. Written by the question types whose calculation follows a rule worth stating: a decimal `multi_direct` is work out 4 × 6 = 24, then put one digit after the point. Only meaningful alongside `steps`.
`steps_words_first`	`true` where `steps_words` stands over the chains rather than under them. The usual place for the sentence is under the calculation it comments on; a question type whose sentence is the step the calculation starts from — what each graduation of an axis is worth, before any counting — puts it first, and this is what a snapshot carries that with. Only meaningful alongside `steps_words`.
`steps_figure`	The same reasoning drawn rather than written — one AML expression, shown beside the `steps` chain behind the same button (stacked under it when the panel is too narrow). Written by the question types that picture their explanation, such as the conversion table of `units_conversion`. Only meaningful alongside `steps`.
`text_scale`	Multiplies this slide's text size (e.g. `0.8`), relative to `rendering.slideshow.font_size`.
`raise`	Lifts this slide's content block up by that many percent (handy for multi-line wordings).
`line_height`	Spacing between wrapped / `\n`-separated wording lines (e.g. `1.1`). Prefer one `\n` per line + this over stacking two `\n`.

text_scale, raise and line_height are per-slide overrides of the global defaults rendering.slideshow.font_size, content_top and line_height (see the Configuration page). They are written by hand when tuning a slideshow, and by the question types whose slide has a shape of its own — area_rectangle, whose wording stands above a figure, lifts its block so the whole of it is not left low on the screen. What a type asks for is a default: the value sits in the snapshot, where whoever edits it afterwards has the last word.