8. Writing Documentation
This site is built with Hugo and the
Hextra theme. Every page is a Markdown
file below content/ in the
KeYProject/key-docs repository.
A push to master rebuilds and republishes the site, so you do not need to
install anything on your computer to write documentation — only to preview it
locally (see Local build and preview). Everything
below is used on this page, so copy from its source.
Where content lives
| Path | Purpose |
|---|---|
content/ | All pages. The directory structure determines the URLs. |
hugo.yaml | Site configuration: menus, base URL, Markdown and math options. |
layouts/ | Local overrides of the theme: callout, snippet, citation and badge templates, Prism and MathJax. |
assets/ | Files processed by Hugo: shared Markdown snippets, CSS, Prism grammars. |
static/ | Files copied verbatim, e.g. static/devel/KeYCodeStyle.xml. |
data/refs.json | Bibliography database used by citations. |
go.mod | Pins the Hextra version (currently v0.13.0). |
The URL of a page is derived from its path: content/user/faq.md becomes
/user/faq/.
Pages, sections and bundles
- Regular page — a single file, e.g.
content/devel/building.md→/devel/building/. - Section landing page —
_index.mdinside a directory, e.g.content/devel/_index.md→/devel/. Its title is the section name in the sidebar, and itsweightorders the section among its siblings. - Leaf bundle — a directory with an
index.mdand the page’s assets next to it, e.g.content/user/proving/proof-caching/index.mdplusProofCachingTree.png→/user/proving/proof-caching/. Assets are referenced relatively:.
Use a bundle whenever a page has images, diagrams or downloads to ship; keep
single-file pages for prose only. A directory must not contain both index.md
and _index.md.
File and directory names become URLs, so use lowercase words separated by
hyphens. When you rename a page, keep old links working with an aliases entry
in the front matter, e.g. aliases: ["/user/old-name/"].
The page title comes from the front matter field title — never from the file
name and never from a heading in the body. The theme renders it once as the
page <h1>; a # heading in the body would produce a second <h1> and break
the table of contents. Start the body with ##.
Page front matter
Front matter is YAML between two --- lines at the top of the file. A typical
page uses:
---
title: "Proof Slicing"
weight: 40
author: "Arne Keller"
date: 2026-06-11
date_label: "June 2026"
valid_for: "KeY-2.12.0"
updated: "June 2026"
---| Field | Required | Effect |
|---|---|---|
title | yes | Sidebar entry and page heading. Quote it when it contains :. |
weight | yes | Integer sort key among sibling pages, ascending. See Navigation and weights. |
author | no | Renders Author: … directly below the title. |
date | no | Machine-readable date (2026-06-11 or RFC3339). Used for ordering; no prose. |
date_label | no | Free text shown in the author line, e.g. "June 2023". Takes precedence over date. |
valid_for | no | Version the page was written for; shown in parentheses after the author line. |
updated | no | Free text; appended to the author line as last updated: …. |
approved | no | Review state, see Review badges. |
approved-on | no | ISO date belonging to approved when the two are written separately. |
aliases | no | List of old URLs that should redirect to this page. |
date_label, valid_for and updated are only rendered when author is also
set — without author the whole author block is skipped. A value in date
that Hugo cannot parse aborts the build, so keep prose dates out of it: put the
machine-readable date in date and the human-readable one in date_label.
Navigation and weights
The sidebar is generated from the content tree, not from a configuration file.
Within a section, pages are sorted by weight in ascending order; sections are
ordered the same way by the weight in their _index.md.
- Leave gaps (
10,20,30, …) so that new pages can be inserted without renumbering everything. - Set an explicit weight on every page of a section. Hugo treats a missing
weight as
0, which sorts before all weighted pages, so an unweighted page silently jumps to the top of the sidebar. - Do not encode ordering in the title. Titles such as
1. Architectureare legacy labels; new pages use a plain title and rely onweight. - The navbar (Home, User Guide, …) comes from
menu.maininhugo.yaml.
For example, the Developer Guide currently orders its sections as
architecture (10), building (20), releasing-central (30),
working-on-code (40), extending (50), library (60), internals (70),
testing (80), this page (90) and appendix (100).
Review badges
The documentation was revised in June 2026 with support from generative AI.
Every hand-written page therefore carries a review state until a KeY core team
member signs it off. The state is derived from approved alone:
| Front matter | Result |
|---|---|
approved missing or empty | Amber pill ⚠ not yet verified at the top of the page, floated right. |
approved: mu 2026-06-19 | Green note in the page footer: ✓ This page was checked by mu on 2026-06-19. |
approved: mu | Same green note, without a date. |
approved: mu plus approved-on: 2026-06-19 | Same green note, with the date from approved-on. |
approved: none | No badge at all (used for generated and index pages). |
The footer of this page shows the green variant. The badge is rendered by
layouts/_partials/custom/content-begin.html and content-end.html; the
styling lives in assets/css/custom.css.
approved. Never
add initials on someone else’s behalf, and do not copy the approved line from
another page. If you have reviewed a page, add your own initials and today’s
date; otherwise leave the field out and the amber badge stays visible.Text features
Ordinary Markdown works as expected: paragraphs, emphasis (*italic*,
**bold**), `inline code`, [links](../building/), blockquotes and
nested lists. A few extensions are enabled in hugo.yaml and worth using.
Headings and anchors
Use ## for sections and ###/#### below it. Add an explicit anchor when
other pages need to link to a specific section:
### Application of a taclet {#sec:taclet-application}The id is used verbatim: #sec:taclet-application within the page,
<other-page>/#sec:taclet-application from another one. Without an explicit
id, Hugo derives a slug from the heading text.
Links between pages are written without the file extension
([Building KeY](../building/)). The theme resolves .md links too, so
../building.md also works — the extension-less form is house style, not a
requirement.
Tables
| Method | Description |
| :----- | :---------- |
| `GET` | Fetch a resource |
| `PUT` | Update a resource || Method | Description |
|---|---|
GET | Fetch a resource |
PUT | Update a resource |
Cells may contain inline Markdown and raw HTML, including icons: supported, not supported.
Icons
{{< icon "name" >}} inserts an inline SVG:
or
.
Names come from Hextra’s bundled icon set; a site-local data/icons.yaml can
add more (key, check-circle, paper-airplane, …). lucide:rocket and
tabler:brand-github use a remote provider fetched at build time. An unknown name is a hard build
error (icon "…" not found), so typos surface immediately.
Lists
- an unordered item
- another one
1. first step
2. second stepTask lists use checkboxes and are not interactive:
- reviewed by a team member
- still waiting for review
Definition lists
`weight`
: Sort key among sibling pages, ascending.
`title`
: Name in the sidebar and page heading.weight- Sort key among sibling pages, ascending.
Footnotes
A footnote reference is [^label]; the definition can live anywhere in the
file and is rendered at the bottom of the page.1
Raw HTML
The Markdown renderer is configured with unsafe: true, so raw HTML passes
through: press Ctrl+S to save. Use this sparingly and
prefer Markdown when it can express the same thing.
Callouts and details
A callout is a coloured box for side remarks. The shortcode is
{{< callout type="info" >}} with the content in the body and a closing
{{< /callout >}}. Content is rendered as Markdown, so lists and code
fences work inside.
default (green, light bulb), info (blue, information), warning (amber,
exclamation), error (red, ban) and important (purple, exclamation circle).
An unknown type falls back to default.The local override in layouts/_shortcodes/callout.html adds a title
parameter, which the upstream theme does not have:
{{< callout type="important" title="Prefer short pages" >}}
Split a page once it needs more than a screen of scrolling.
{{< /callout >}}Rendered result:
Without title=, the box shows just the icon next to the content. You can
also pass icon= or emoji= to replace the default symbol.
Collapsible details
For optional asides use the details shortcode. Its content is Markdown as
well; closed="true" starts the block collapsed instead of open.
{{% details title="Why is there no centred alignment?" %}}
Markdown has no alignment attribute; use a raw HTML `figure` instead.
{{% /details %}}Why is there no centred alignment?
Markdown has no alignment attribute; use a raw HTML figure instead (see
Images and downloads).
This aside starts collapsed
Pass closed="true" to hide optional material until the reader opens it.
Code blocks
Fenced code blocks are highlighted in the browser by
Prism.js. Chroma is still configured in hugo.yaml, but
layouts/_partials/components/codeblock.html bypasses it for fences and emits
a language-… class instead, so there is no server-side highlighting. Put the
language directly after the opening fence:
```java
public void pay(int amount) {
balance -= amount;
}
```public void pay(int amount) {
balance -= amount;
}The following fence languages are wired up in
layouts/_partials/components/codeblock.html:
| Fence | Use for |
|---|---|
java | Java source |
jml | JML specifications |
key | KeY problem files and taclets |
python, bash, yaml, json | scripts and configuration |
javascript, js | JavaScript source |
lisp, elisp, emacs | Lisp source |
markdown | Markdown examples (as on this page) |
text | plain text, ASCII art, command output |
diff-<lang> | a diff (-/+ lines) highlighted with <lang>, e.g. diff-java, diff-key, diff-text |
A few more grammars are bundled (c, cpp, css, html/xml, latex,
groovy, ocaml, properties). Aliases: shell/sh → bash, c++ → cpp,
yml → yaml. Any other language renders uncoloured but without error.
Supporting a new one means vendoring prism-<lang>.min.js into assets/js/prism/,
listing it in layouts/_partials/custom/head-end.html, and adding the fence
alias to the map in components/codeblock.html.
Diffs
Use a diff-<lang> fence for diffs. Lines starting with - are marked as
removed and lines starting with + as added; a leading space marks an unchanged
line, which keeps the inner language’s highlighting. For example:
```diff-json
\proofObligation {
- "contract": "simple_evoting.Server[java.lang.Object::<inv>()].JML accessible clause.0",
+ "contract": "simple_evoting.Server[java.lang.Object::$inv()].JML accessible clause.0",
"class": "de.uka.ilkd.key.proof.init.DependencyContractPO",
}
``` \proofObligation {
- "contract": "simple_evoting.Server[java.lang.Object::<inv>()].JML accessible clause.0",
+ "contract": "simple_evoting.Server[java.lang.Object::$inv()].JML accessible clause.0",
"class": "de.uka.ilkd.key.proof.init.DependencyContractPO",
}Inline code uses single backticks: `key`.
Tabs
Tabs group alternative views of the same thing, typically two languages or a
description next to an example. The first tab is selected by default;
selected=true on a tab selects another one. Tab selection can be
synchronised across the page with tabs.sync in the front matter (or
params.page.tabs.sync in hugo.yaml).
{{< tabs >}}
{{< tab name="Java" >}}
…
{{< /tab >}}
{{< tab name="JML" >}}
…
{{< /tab >}}
{{< /tabs >}}Rendered result:
public class PayCard {
private int balance;
public void pay(int amount) {
balance -= amount;
}
}A tab also takes icon=; keep tab contents short — a tab should not scroll.
Mathematics
Math is typeset by MathJax. Exactly two delimiter
pairs are enabled: $…$ for inline math and $$…$$ on separate lines for
display math.
$$
\operatorname{ker} f = \{g \in G : f(g) = e_H\}
$$The homomorphism $f$ is injective if and only if its kernel is the singleton set $\{e_G\}$.
\(…\) and \[…\] are deliberately not math delimiters here: KeY program
modalities are written exactly that way and must stay literal in code and
prose. Always use dollar signs for mathematics.Mermaid diagrams
A fenced mermaid block is rendered as a diagram; no front matter flag is
needed, the theme loads Mermaid automatically when a page contains one.
```mermaid
graph LR
A[Write Markdown] --> B{Hugo build}
B -->|success| C[Publish]
B -->|error| A
```
graph LR
A[Write Markdown] --> B{Hugo build}
B -->|success| C[Publish]
B -->|error| A
Flowcharts, sequence diagrams, state diagrams, class diagrams and
entity-relationship diagrams are all supported. Diagrams are drawn in the
browser, so they do not appear in plain-text exports. For ASCII art use a
text fence: it is uncoloured and keeps its alignment.
Citations
The bibliography is generated from refs.bib into data/refs.json by
scripts/bib_to_json.py. To cite a new work, add its BibTeX entry to
refs.bib, regenerate the data file, and commit both:
python3 scripts/bib_to_json.py refs.bib data/refs.jsonThen cite by key — the shortcode renders the surnames plus the year:
The KeY book {{< cite "KeYBook2016" >}} describes the calculus in detail.The KeY book Ahrendt et al. 2016 describes the calculus in detail.
The reference list itself comes from {{< bibliography >}}, which renders
every entry sorted by key with an anchor #ref-<KEY>. It already lives on the
Quicktour page; cite
links there, or locally when the page renders the list. An unknown key only
emits a warning, so check the build log.
Shared snippets
Content that appears on several pages (for example the strategy cost table) is
kept once under assets/snippets/ and included where needed:
{{< snippet "snippets/costband-table.md" >}}The file is rendered as Markdown at the point of inclusion:
Rendered example: the cost band table
| Band | Value | Meaning |
|---|---|---|
BLOCK_CONTRACT | Long.MIN_VALUE | apply a block/loop contract instead of executing the block |
LOOP_INVARIANT | −20000 | apply a loop invariant instead of unrolling |
CLOSE | −15000 | close the goal (eager closure is completeness-neutral) |
REWRITE | −11000 | one-step simplification and decidable ground rewrites (concrete) |
SUBST | −10000 | force a pending substitution / eager equality (try_apply_subst) |
ELIMINATE | −8000 | eliminate updates and literals |
DECOMPOSE | −7000 | non-splitting sequent decomposition (alpha rules, update-apply-on-update) |
TYPE | −6000 | type reasoning (delta rules, type hierarchy) |
NORMALIZE | −5000 | canonicalize / order / commute terms |
SIMPLIFY | −4500 | safe, size-reducing definitional simplification and SE steps |
EXECUTE | −4000 | a symbolic-execution program step / state merge |
SOLVE | −3000 | solve direct (in)equations; apply query axioms |
ENLARGE | −2000 | useful but size-increasing simplification (e.g. comprehension / map unfolding) |
PREFER | −500 | minor local structural preference |
DEFAULT | 0 | no strategic bias — apply in due (age) order |
DEFER | 500 | lazy definitional unfolding, applied only when needed |
DEFER_STRONG | 10000 | strongly defer |
LAST_RESORT | 1000000 | finite last resort — reachable, but only when nothing else applies |
Update the snippet once and every page follows — nothing drifts. Real use: Strategy Costs.
Images and downloads
Page-specific images belong in the page bundle, next to index.md, and are
referenced relatively. A Markdown image with a title renders as a figure with
a caption:

Use descriptive alt text — it is what screen readers and search engines see.
Files shared by many pages live in static/ and are referenced by an absolute
site path such as /images/key.png (Hugo’s render hook resolves it against
baseURL). For more markup than a caption — a width, say — write a raw HTML
figure without a markdown attribute. Raw HTML is not rewritten by Hugo,
so keep the src bundle-relative; a root-absolute /… would point outside the
deployed sub-path and 404:
<figure>
<img src="./images/key.png" alt="The KeY logo" width="96">
<figcaption>The KeY logo, embedded as raw HTML.</figcaption>
</figure>
Downloads follow the same rule: a bundle file is linked relatively
([quicktour.zip](quicktour.zip)), a shared file under static/ by absolute
path ([KeYCodeStyle.xml](/devel/KeYCodeStyle.xml)).
Local build and preview
You need Hugo extended 0.146 or newer (CI pins 0.161.1), a Go toolchain for the Hextra module, and lychee for the link check.
make prepare # hugo mod tidy — resolve the Hextra module
make serve # hugo server --logLevel debug --disableFastRender -p 1313
make build # hugo --gc --minify, output in public/
make check # build to /tmp/keydocs-check, then lychee link checkmake serve listens on http://localhost:1313 and reloads on change. Without
make, the same commands are:
hugo server --logLevel debug --disableFastRender -p 1313
hugo --gc --minifyhugo server renders shortcodes, math and Prism highlighting exactly as the
deployed site does. Never edit files under public/ — they are overwritten on
the next build. make check rebuilds with --baseURL "/" so that lychee can
resolve absolute paths, and checks only links into the generated site
(--offline). The sidebar’s Edit this page link opens the page source under
content/.
Deployment
.github/workflows/pages.yaml builds the site with hugo --gc --minify on
every push to master or main, on pull requests, and weekly for the
generated proof-script reference; only master deploys, to GitHub Pages at
https://keyproject.github.io/key-docs/.
- Template and shortcode errors, unknown icon names and unparsable
datevalues abort the build, so CI catches them before merging. - An unknown citation key only emits a warning: the build passes and the page
shows
[KEY]. - Broken internal links are caught by
make check(lychee), not by the CI build — run it before pushing. public/andresources/are build output; never commit them.
Common mistakes
- A
#heading in the body — the title already is the<h1>. Use##. - A page without
weight— it sorts to the top of its section. - A non-parsable
datesuch asJune 2023— it aborts the build; use ISO or RFC3339 indateand put prose indate_label. - A copied
approvedline naming somebody else — only the reviewer signs off. \(…\)or\[…\]used as math delimiters — use$…$and$$…$$.- A root-absolute
/…src in raw HTML — it bypassesbaseURLand 404s; use a./…bundle path instead.
Footnotes are numbered automatically and collected at the bottom of the page; use them for asides, not for essential information. ↩︎