Documentation for the KeY Theorem Prover, published at https://keyproject.github.io/key-docs/.
Author: Alexander Weigl weigl@kit.edu
The site is built with Hugo and the
Hextra theme. Hextra is consumed as a Hugo
module and pinned in go.mod; there is no theme checkout to maintain.
- Hugo extended 0.170.0 (the version used by CI; any recent extended build works)
- Go 1.27 or newer, for Hugo modules
- Git
- lychee, optional, for
make check
make prepare # hugo mod tidy: resolve/download the pinned theme module
make serve # live preview on http://localhost:1313
make build # production build into public/
make check # build into /tmp/keydocs-check and check internal links
make ci # build + check
make update # update the Hextra module and tidy go.mod/go.sum
make version # compare the local Hugo with the CI-pinned versionThe underlying commands are hugo mod tidy,
hugo server --logLevel debug --disableFastRender -p 1313,
hugo --gc --minify and a scratch build followed by lychee. make check
resolves every internal link against the generated site (anchors are not
verified) and fails with an explanatory message if lychee is not installed.
Never edit files under public/ or resources/; they are regenerated.
A detailed authoring guide with live examples lives at
Developer Guide → Writing Documentation
(published at /devel/writing-documentation/).
| Path | Purpose |
|---|---|
content/ |
All pages. Directory structure determines URLs. |
hugo.yaml |
Site configuration: menus, base URL, Markdown, math, search. |
layouts/ |
Theme overrides: callout, snippet, citation, badges, Prism, MathJax. |
assets/ |
Processed by Hugo: shared snippets, CSS, Prism grammars. |
static/ |
Copied verbatim: images, PDFs, XML schemas, downloads. |
data/refs.json |
Bibliography database used by citations. |
scripts/ |
Migration and bibliography helpers (not needed to build). |
go.mod, go.sum |
Pin the Hextra version (currently v0.13.0). |
.github/workflows/pages.yaml |
CI build and GitHub Pages deployment. |
Pages live under content/; content/user/faq.md becomes /user/faq/.
- Regular page: a single
.mdfile. - Section landing page:
_index.mdin a directory; its title andweightplace the section in the sidebar. - Leaf bundle: a directory with
index.mdplus its images/downloads, e.g.content/user/getting-started/loading/index.md. Reference assets relatively (./figure.png,./quicktour.zip).
Every page starts with YAML front matter:
---
title: "Proof Slicing"
weight: 40
author: "Arne Keller"
date: 2026-06-11
date_label: "June 2026"
valid_for: "KeY-2.12.0"
approved: mu 2026-06-19
---titleis the only page heading; do not add a#heading in the body. Start the body with##.weightorders sibling pages ascending. Set it on every page and leave gaps (10, 20, 30, …). A missing weight sorts to the top.author,date_label,valid_forandupdatedrender in the author line.datemust be an ISOYYYY-MM-DD; usedate_labelfor free text.- The sidebar is generated from the content tree — there is no navigation file
to edit. Only the main menu is configured under
menu.maininhugo.yaml. - Use lowercase hyphenated file names. When renaming, add
aliases: ["/user/old-name/"]to keep old URLs working.
The review state comes from the approved field:
| Front matter | Rendered result |
|---|---|
| missing/empty | Amber ⚠ not yet verified pill at the top |
approved: mu 2026-06-19 |
Green footer note naming reviewer and date |
approved: mu + approved-on: 2026-06-19 |
Same note, date from approved-on |
approved: none |
No badge (generated and index pages) |
Only the person who actually reviewed a page may be named. Do not invent
initials or copy an approved line from another page. Generated pages keep
approved: none.
| Shortcode | Use |
|---|---|
{{</* callout type="info" title="…" */>}} … {{</* /callout */>}} |
Coloured box; types default, info, warning, error, important, plus optional title, icon, emoji |
{{%/* details title="…" */%}} … {{%/* /details */%}} |
Collapsible aside (closed="true" starts collapsed) |
{{</* tabs */>}} / {{</* tab name="…" */>}} |
Tabbed alternatives |
{{</* snippet "snippets/costband-table.md" */>}} |
Include a Markdown file from assets/ |
{{</* cite "KeYBook2016" */>}} |
Inline citation from data/refs.json |
{{</* bibliography */>}} |
Reference list with #ref-KEY anchors |
{{</* icon "check-circle" */>}} |
Inline icon |
Cite with the BibTeX key; the bibliography renders every entry sorted by key.
An unknown key renders as [KEY] and emits a build warning. refs.bib is the
source for data/refs.json, which is regenerated with
scripts/bib_to_json.py (standard library only; scripts/requirements.txt is
only needed for the one-off migration helpers).
Code fences are highlighted in the browser by Prism. Wired languages include
java, jml, key, python, bash/shell, yaml, json, javascript/js,
lisp/elisp, markdown, c, cpp, css, html/xml, latex, groovy,
ocaml and properties.
text and unknown languages render uncoloured but do not fail the build.
Diff fences use diff-<language> (for example diff-java or diff-key) and
highlight added and removed lines with the inner language's grammar.
Math is typeset by MathJax with exactly two delimiter pairs: $…$ inline and
$$…$$ display. Do not use \(…\) or \[…\]: KeY program modalities are
written that way and must stay literal.
A fenced mermaid block becomes a diagram; no front-matter flag is needed.
Put page-specific assets in the leaf bundle and link them relatively. Shared
assets live under static/ and are linked with absolute paths, e.g.
/images/key.png, /devel/KeYCodeStyle.xml, /old/Architecture.pdf or
/smt/smtDoc.pdf. Markdown images with a title render as captioned figures.
.github/workflows/pages.yaml builds and deploys the site:
- on pushes to
masterandmain, on pull requests targeting either branch, on a weekly schedule, and on manual dispatch; - checks out full history (
fetch-depth: 0) forenableGitInfo; - installs Go 1.27.x and Hugo extended 0.170.0;
- tries to download the
varcond-script-docsartifact from the latest successful nightly build ofKeYProject/keyand unpack it intocontent/user/proof-scripts/. This is best-effort: the upstream nightly does not currently publish that artifact, so the checked-incommands.mdis the effective source. Restoring the artifact also needs a token with read access toKeYProject/key; - strips the generator's obsolete stylesheet from
commands.mdand keepsapproved: none; - builds with
hugo --gc --minify --baseURL …and uploads./public; - deploys to GitHub Pages only from
master.
Pushes to master publish automatically. Pull requests run the same build as a
check; broken shortcodes, missing icons and unparsable front matter fail the
build, while unknown citation keys only emit a warning. CI does not run the link
checker, so run make check locally before pushing.