Style guide · IOAI Guide

This page is a reference for writers. The text here only describes the components; module content lives in src/modules/.

Headings

Use ## for sections and ### for subsections. They appear automatically in the On this page list.

A subsection

Body text is set in STIX Two Text, the same face as the main SOTA site.

Math

Write inline math between single dollar signs, like $\hat{y} = w^\top x + b$ , and display math between double dollar signs:

\mathrm{MSE} = \frac{1}{n} \sum_{i=1}^{n} \left(y_i - \hat{y}_i\right)^2

Code

Fence code with the language name so it gets highlighted.

import numpy as np

def mse(y_true, y_pred):
    # Mean squared error of two arrays
    return np.mean((y_true - y_pred) ** 2)

Callouts

Write them like this. The available types are definition, note, tip, warning, example and exercise.

{% callout "definition", "Optional title" %}
Markdown goes here.
{% endcallout %}

To hide an exercise's answer until the reader clicks, wrap it in <details>. Keep the blank lines around the answer so it is still read as Markdown.

{% callout "exercise", "Optional title" %}
The question.


Show answer

The answer.


{% endcallout %}

Algorithm box

Algorithm Mini-batch gradient descent

w = initial weights
while the validation loss is still improving:
    batch = small random sample of the training set
    w = w - learning_rate * gradient of the loss on batch

{% algorithm "Title" %}
```text
function name(arguments):
    for each item in items:
        do something with item
    return result
```
{% endalgorithm %}

Expandable box

Use it for optional detail, such as a derivation, that a reader can skip without losing the thread.

Optional Why the square expands this way

Multiplying out $(a + b)(a + b)$ gives four products, $a^2 + ab + ba + b^2$ , and the two middle ones are equal, so $(a + b)^2 = a^2 + 2ab + b^2$ .

{% expand "Title" %}
Markdown goes here, including math and code.
{% endexpand %}

Term explanation

A small "i" button right after a harder term opens a short explanation in a pop-up. Keep the explanation to a few sentences; longer material belongs in an expandable box.

The log loss is convex, so gradient descent can find its minimum.

The log loss is convex{% info "Convex function" %}Explanation in Markdown.{% endinfo %}, so ...

Tables

Markdown tables get the same thin rules as the rest of the site.

Metric	Formula
Precision	$\frac{TP}{TP + FP}$
Recall	$\frac{TP}{TP + FN}$

Resources and practice problems

These two tables are built from a module's front matter, so writers only fill in lists at the top of the file:

resources:
  - { source: "Book or site", title: "Chapter or page", url: "https://...", note: "Why it helps" }
problems:
  - { source: "IOAI 2025", name: "Task name", url: "https://...", difficulty: "Medium", tags: ["vision"] }