Maths and diagrams

LaTeX formulas, theorem environments and Mermaid diagrams in guide pages.

Guide pages carry mathematics and diagrams without any setup: the syntax is part of the MDX pipeline, and nothing needs enabling in site.yaml.

What each one costs

Maths and diagrams are optional dependencies. A site that does not ask for them never installs them, and the engine renders without them rather than failing over a package nobody wanted.

	Install	Sent to the browser
Mindmaps	nothing — built in	nothing
Maths	~50 MB	nothing (MathJax typesets to SVG at build time)
Mermaid diagrams	~100 MB	~10 MB, and only on pages that have one

Turn them on with zel build --features maths,diagrams, or by picking the container image that has them. Ask for neither and $…$ stays as written and a mermaid fence renders as its source — which is what a site with no formulas and no diagrams expects anyway.

LaTeX

Inline maths goes between single dollars, display maths between double ones.

The sum $\sum_{k=1}^{n} k = \frac{n(n+1)}{2}$ is Gauss's, and in display form:

$$
\int_{-\infty}^{\infty} e^{-x^2}\,dx = \sqrt{\pi}
$$

The sum is Gauss's, and in display form:

A wide derivation gets its own scrollbar rather than widening the page:

Theorem environments

<Theorem> covers the usual environments — theorem, lemma, corollary, proposition, definition, example and remark — and <Proof> is the one you write most often.

mdx

<Theorem kind="theorem" number="1" title="Cauchy–Schwarz">
For all real $a_k$ and $b_k$, the inequality above holds.
</Theorem>

<Proof>
Consider the quadratic $q(t) = \sum (a_k t - b_k)^2 \geq 0$.
</Proof>

Theorem 1 (Cauchy–Schwarz)

For all real and , the inequality above holds, with equality exactly when the two sequences are proportional.

Proof

Consider . A quadratic that is never negative has non-positive discriminant, and expanding gives precisely the claim.

Definition 1 (Inner product)

A map that is linear in its first argument, symmetric, and positive definite.

Numbering is yours

number is written, not counted. MDX compiles each page on its own with no shared render pass, so a counter would restart wherever a component happened to re-render — and a theorem whose number moves is worse than one with no number. Omit number, or pass unnumbered, for a one-off.

Mermaid diagrams

A mermaid fence is drawn rather than highlighted. Every diagram type in the grammar works, mindmaps included.

Flowchart

```mermaid
flowchart LR
  A[content/] --> B{zellij}
  B --> C[Marketing pages]
  B --> D[Guide pages]
```

Mindmap

```mermaid
mindmap
  root((Zellij))
    Content
      site.yaml
      sections/
    Output
      Pages
      Guides
```

flowchart LR
  A[content/] --> B{zellij}
  B --> C[Marketing pages]
  B --> D[Guide pages]
  C --> E[Static site]
  D --> E

A mindmap, from the same fence:

mindmap
  root((Zellij))
    Content
      site.yaml
      menu.yaml
      sections/
    Guides
      _sidebar.yaml
      MDX pages
    Output
      Static HTML

And a sequence, since documentation explains protocols more often than it explains trees:

sequenceDiagram
  participant A as Author
  participant Z as Zellij
  participant S as Site
  A->>Z: writes content/
  Z->>Z: validates and resolves
  Z->>S: renders static pages
  S-->>A: fails the build on a broken link

Mindmaps

A mindmap fence is YAML, and it is drawn during the build rather than in the browser:

```mindmap
Zellij:
  Content:
    - site.yaml
    - menu.yaml
    - sections/
  Guides: [_sidebar.yaml, MDX pages]
  Output: Static HTML
```

A mapping is a node and its children, a list is a set of siblings, and a bare string is a leaf. That is the whole syntax.

A deeper tree stays readable because each column is only as wide as its widest label:

Colour-coded maps

A mindmap is the quickest way to draw a hierarchy, but its renderer draws no arrowheads and gives you one colour per branch and no say in which. When the picture is the point — a structure someone will study rather than glance at — reach for a flowchart and colour the branches yourself:

```mermaid
flowchart LR
  P([Business Plan])

  P --> S1[1. Executive Summary]
  P --> S2[2. Business Description]
  S2 --> S2a[Mission Statement]
  S2 --> S2b[Ownership]

  classDef gold  fill:#fff,stroke:#c8a02c,stroke-width:2px,color:#8a6d1b
  classDef slate fill:#fff,stroke:#4a4f57,stroke-width:2px,color:#33373d

  class S1 gold
  class S2,S2a,S2b slate
```

flowchart LR
  P([Business Plan])

  P --> S1[1. Executive Summary]
  P --> S2[2. Business Description]
  S2 --> S2a[Mission Statement]
  S2 --> S2b[Ownership]
  P --> S3[3. Product]
  S3 --> S3a[Opportunities]
  S3 --> S3b[Threats]

  classDef gold  fill:#fff,stroke:#c8a02c,stroke-width:2px,color:#8a6d1b
  classDef slate fill:#fff,stroke:#4a4f57,stroke-width:2px,color:#33373d
  classDef green fill:#fff,stroke:#2f855a,stroke-width:2px,color:#276749

  class S1 gold
  class S2,S2a,S2b slate
  class S3,S3a,S3b green