Technical content

DataLeaf includes render hooks and shortcodes for technical and scientific writing.

Lists, term pages, documentation contents, and search results share one entry: the title, a plain-text summary, and beside them the date, reading time, and up to four tags. From 72rem the date and metadata sit in a rail beside the title, as on articles. To change the summary, override layouts/_partials/summary.html.

A minimal post:

---
title: "A technical note"
date: 2026-09-29
tags:
  - statistics
  - python
categories:
  - research-notes
---

Tags become links to their taxonomy pages. A description in the front matter appears under the title as a subtitle.

Articles are laid out as a manuscript. On wide screens, from 72rem, a side rail holds the publication date, reading time, configured author, and tags, followed by a table of contents that stays in view while reading; the text sits beside it at the reading measure. On smaller screens the same information follows the title in the reading flow, before the text.

Tables, display equations, and code blocks wider than the reading measure may use the space beside it, up to --dl-wide-content, and scroll beyond that; paragraphs keep the measure.

Use ordinary fenced Markdown:

def variance(values: list[float]) -> float:
    """Return the population variance of non-empty values."""
    if not values:
        raise ValueError("values must not be empty")
    mean = sum(values) / len(values)
    return sum((value - mean) ** 2 for value in values) / len(values)

DataLeaf uses Hugo’s code-block render hook and Chroma classes. Code is set as part of the article rather than as an editor panel: a quiet tint of the page between hairlines, the language as a small label, and a restrained syntax palette in each color scheme. Long blocks scroll horizontally on narrow screens.

Hugo’s fenced-code options such as {linenos=table hl_lines=[2]} and {linenos=inline} retain aligned line numbers, set off by a hairline, and highlighted lines, which are tinted and marked in the margin. Focus the code region and use the arrow keys to scroll a long line; table-style line numbers remain alongside the code.

Line numbers are a visual gutter: DataLeaf hides them from assistive technology and keeps the table-style gutter out of the Tab order, so screen readers read only the code and keyboard users reach one scroll region per block. Linked line numbers (anchorlinenos=true) are left as ordinary links.

Inline:

\(E[X] = \mu\)

Display:

$$
\hat{\mu} = \frac{1}{n}\sum_{i=1}^{n} x_i
$$

With params.math.engine = "hugo", Hugo renders the expression to MathML during the build; no math JavaScript is loaded. Invalid TeX stops the build with the file, position, and KaTeX error.

Display equations have a keyboard-focusable scrolling region. Wide expressions keep their mathematical layout without widening the page. Browsers cannot wrap an inline formula, so put long expressions in display math, especially for readers who enlarge text on small screens.

Build-time MathML is adjusted for browsers that implement MathML Core, such as Chrome and Edge:

• Formulas use STIX Two Math, a font with an OpenType MATH table, so large operators, roots, and stretchy brackets are drawn correctly. The theme bundles it and downloads it (about 400 KB) only on pages with formulas, and only when it is not installed. Override --dl-font-math to use another MATH-table font.
• Styled letters become Unicode mathematical characters: \mathbb{R} renders as ℝ, \mathcal{N} as 𝒩, and \mathbf{x} as 𝐱. Bold Greek letters are made bold with CSS.
• aligned and align environments line up at their alignment points, and cases rows are left-aligned. A \tag{…} label follows its equation rather than sitting at the right margin.

Math also works in headings, where the table of contents shows it rendered, and in table cells. Inside a table cell, write \lvert x \rvert or \lVert x \rVert instead of |x|: a literal | ends the Markdown cell before the math is read.

With another params.math.engine, DataLeaf emits \(…\) for inline and \[…\] for display math, whichever passthrough delimiters the source uses. Configure your renderer for those delimiters. Without JavaScript, readers see the TeX source.

{{< callout type="note" title="Model assumption" >}}
The residuals should be inspected before relying on the fitted interval.
{{< /callout >}}

Supported types are note, tip, warning, and important. Without a title, the callout is titled with its translated type, such as “Warning”. With a custom title, a visually hidden prefix such as “Warning:” keeps the type available to screen readers, since the colored border alone does not convey it. Other type values keep their dataleaf-callout--* class for custom styling and are announced as notes.

Definition:

{{< definition title="Weak stationarity" >}}
A process is weakly stationary when its mean is constant and covariance depends only on lag.
{{< /definition >}}

The same pattern is available for:

• theorem
• remark
• example
• proof

A proof accepts an optional title parameter and renders an end-of-proof symbol, announced to screen readers as “End of proof”.

Statements are set as in a journal rather than as alert boxes: a small label names the kind, a thin rule in a muted color marks the block, and the body follows in the reading face. Theorem bodies are italic; definitions, remarks, and examples stay upright. A proof has an italic label and closes with the end-of-proof mark. Callouts, being exceptional content, keep a restrained tint and a rule in their type’s color.

Statement, proof, and callout titles accept inline Markdown and math, for example title="Convergence in \(L^2\)". Accessible names use the formula’s visible symbols.

Each statement and proof is a named group, such as “Definition: Weak stationarity”, so assistive technology can report where it starts and ends. Statements are not headings and do not appear in the table of contents or add landmarks.

Use normal Markdown tables. DataLeaf wraps them in a horizontally scrollable, keyboard-focusable region on small screens.

Tables follow journal practice: rules above and below the table and under its header, no vertical lines or cell borders, and edges aligned with the text. Compact tables fit the available width. Wider tables scroll when their cell contents need more space; focus the region and use the arrow keys to inspect offscreen columns. Digits use tabular lining figures, so right-aligned numeric columns (---: in Markdown) line up.

Give column headers words, not only a symbol: write Draws \(n\) rather than \(n\). Accessibility checkers treat a math-only header as empty, and screen-reader support for math in headers varies.

A standalone Markdown image with a title becomes a figure with a caption:

![Residual diagnostic](images/residuals.svg "Figure 1. Residual diagnostics.")

Images resolve against their source page bundle, including content composed through Hugo’s RenderShortcodes, then against global resources under assets/. For files in static/, use paths without a leading slash, such as images/residuals.svg, to preserve a deployment subpath. Explicit ./ and ../ paths remain relative to the page when no resource matches; /images/... deliberately refers to the domain root. External URLs and query strings/fragments are preserved. Empty Markdown alt text produces alt="" for decorative images.

Heading, image, and table hooks preserve Markdown attributes enabled by your Goldmark parser configuration.

Figures keep their intrinsic size up to the available content width and scale down proportionally. Small diagrams are not enlarged to fill the reading column. PNG, JPEG, and GIF figures from page bundles or assets/ get width and height attributes from the file, so the page does not shift as they load; explicit Markdown attributes take precedence.

Figure images sit on a light backdrop in both themes, so plots exported with a transparent background and dark ink stay legible in dark mode. Set --dl-figure-bg: transparent if your figures adapt to dark mode themselves.

To render standalone images as figures, configure:

[markup.goldmark.parser]
  wrapStandAloneImageWithinParagraph = false

A figure can also use the space beside the reading measure. Enable block attributes and mark the image wide:

[markup.goldmark.parser.attribute]
  block = true

![Posterior density](posterior.svg "Figure 2. Posterior density.")
{.wide}

Use standard Goldmark footnotes:

Calibration should be checked separately from discrimination.[^calibration]

[^calibration]: A well-ranked model can still be poorly calibrated.

DataLeaf styles the footnote list and back references as part of the article flow.

Goldmark’s default back-reference is the symbol “↩︎”, which screen readers announce by its character name. A single-language site can give it a spoken name with Hugo’s site-wide setting:

[markup.goldmark.extensions.footnote]
  backlinkHTML = '<span aria-hidden="true">&#x21a9;&#xfe0e;</span><span class="dataleaf-visually-hidden">Back to reference</span>'

DataLeaf does not set this itself because the text cannot be translated per language: a language-level markup table replaces the entire site-level markup configuration rather than merging with it.

Nested, ordered, and loose lists may contain code blocks and display math. Hugo’s default Goldmark extensions also provide definition lists, styled with bold terms, and task lists:

Effective sample size
: The number of independent draws with the same variance as the correlated chain.

- [x] Proofs checked
- [ ] Replications archived

Task-list checkboxes replace the bullet and are named after their item text for screen readers.