Math
KaTeX renders mathematics to HTML + MathML at build time. Pages with formulas load one local KaTeX stylesheet.
They load no JavaScript and contact no remote mathematics service.
Use \(…\) for inline formulas, $$…$$ or \[…\] for display formulas, or math and chem fences.
For TikZ or macro packages unsupported by KaTeX, use a pre-rendered image.
Validate generated formulas with Hugo Extended 0.168.0 and the bundled stylesheet. TeX and MathML remain unchanged. No browser mathematics runtime or extra site switch is needed.
Site prerequisites
math and chem fences need no configuration.
The $$, \[…\], and \(…\) delimiters need Goldmark’s passthrough extension.
Hugo does not merge theme markup configuration. Put this block in your site’s configuration file.
This site uses:
Configuration defines each key. Delimiters must not conflict with prose.
A single $ is deliberately not configured, so prices such as “$5” are never treated as mathematics.
Shortest form
Put inline formulas inside sentences. Keep surrounding spaces and punctuation outside the delimiters.
The shared buffer hit ratio is , where is blks_hit and is blks_read.
Display formulas
Put a formula in its own paragraph between $$ delimiters. It displays larger and centered.
\[…\] has the same effect.
A B-tree with fan-out over keys has height:
Long formulas scroll horizontally within the reading column instead of widening the layout. In print, they remain static.
The math fence
The math fence is another form for display formulas. It needs no site passthrough configuration.
GitHub displays its source as an ordinary code block.
This is Little’s law for a connection pool. In steady state, required concurrency equals arrival rate multiplied by mean response time. The pool is usually much smaller than the client count.
Chemistry and units
The chem fence uses KaTeX’s mhchem extension with a \ce{…} body. This extension also typesets physical units.
For the syntax see the mhchem manual.
Numbered equations
An attribute line below a display formula creates a numbered equation.
num is an author-provided string, such as 3-1 or 5.3. The theme never counts. #id defaults to eq-<num>.
The number appears to the right of the formula with a localized “Equation” prefix.
See Equation 3-1: multiply by the retention period for the floor on archive disk size.
caption is optional plain text. #id and caption require num.
Incomplete or duplicate targets warn and remove unusable parts or keep the first target.
On narrow screens, long captions wrap within the reading column without widening the page.
Cross references
Reference numbered equations with ordinary links, as above.
For cross-page references or automatic “Equation N” labels, use xref:
Capacity planning starts from Equation 3-1.
xref may appear before its target. Forward references are allowed.
For the book-wide equation list and book-equations index, see publishing books.
The eq shortcode
Use eq when your site cannot enable passthrough. It uses the same KaTeX renderer.
Without parameters, it displays an unnumbered formula. With num, it is equivalent to the attribute-line form.
This site enables passthrough, so ordinary authoring uses $$.
Use eq for migrated manuscripts or sites whose hugo.yml cannot be changed.
Output
| Output | Shape |
|---|---|
| HTML | KaTeX HTML + MathML rendered at build time; this page also loads a local katex.min.css, which pages without formulas never load |
| Same as HTML, static, long formulas do not scroll | |
| Markdown | The source as written: $$ blocks with their attribute line, math / chem fences, \(…\); the eq shortcode emits **Equation 3-2.** caption plus a $$ block |
| RSS | The same static text as Markdown |
No form loads JavaScript.
Parameter reference
Four spellings:
The attribute line {…} under a display formula:
The eq shortcode:
Invalid TeX warns and preserves the expression in ordinary previews. The message includes KaTeX details and the source position. Review the warning and rendered fallback before publication.
Limits
- The site’s
markup.goldmarkpassthrough extension controls whether$$,\[…\], and\(…\)render. The theme does not read amath: truefront matter key. Without configuration,$$appears literally. Themathfence andeqwork without this configuration. - Only
$$blocks andeqsupport numbering. Themathfence accepts no attribute line. Use another form when you need numbers. - Authors provide numbers. The theme neither counts nor renumbers. If you reorder chapters, edit
num. - Inline formulas accept no attributes. Attribute lines apply only to display formulas.
captionis plain text. Markdown in captions is not parsed.
Related
- Code blocks — fence attributes and numbered examples
- Images — figures use the same
{#id num=}numbering - Publishing books — lists of equations and cross-page references
- Configuration — the
markup.goldmarkkeys