Code, maths and diagrams

Code

@code(language="python", filename="train.py")
def train(model, data):
    return model.fit(data)
@endcode

Argument	Meaning
`language`	Used for syntax highlighting, and by editors to highlight the block inline
`filename`	Shown as a label
`caption`	Shown beneath

A @code block with no language is a warning: highlighting cannot be applied and a reader cannot tell what it is looking at.

Highlighting happens when the document is rendered, not by a script in the page, so exported HTML stays self-contained and works offline. Comments, strings, numbers and keywords are wrapped in tok- classes that the surrounding stylesheet colours; a language the renderer does not know is escaped and left plain rather than guessed at.

The payload is taken literally. Nothing inside is parsed as XTXT, so a code sample can contain @ characters freely.

note

Title: One exception, and it matters Because blocks do not nest, a @code block cannot contain @endcode — the first one closes it. Documenting XTXT in XTXT runs into this immediately; the examples on this page use @raw for exactly that reason. See Limitations.

Maths

@math(caption="Mass–energy equivalence")
E = mc^2
@endmath

The payload is passed through untouched. XTXT does not specify a maths syntax — a renderer is free to hand it to KaTeX, MathJax or nothing at all.

Diagrams

@mermaid(caption="Parse pipeline")
graph LR
  A[source] --> B[parse] --> C[AST] --> D[render]
@endmermaid

Rendered as a <pre class="mermaid"> block. Diagrams only draw when the page loads Mermaid, which is opt-in:

xtxt export notes.xtxt html --mermaid

Off by default so exported output stays self-contained and works offline. With the flag, the loader comes from a CDN — which means the page needs a network to draw its diagrams. That trade is yours to make per export.