Write a document

Every document starts with a block of properties between two --- lines, one Key: value per line:

---
Author: Ann Lopez
Category: Procedure
Date: 2026-10-03
Tag: backup, postgresql
---

• Give a property several values by separating them with commas.
• Use any property names you like. Keep them singular and capitalised (Tag, Team, Product): Tag and tag are different properties.
• Date is optional. Write it as 2026-10-03 or 2026-10-03 14:30.

Which properties to use depends on what you write and on the theme. The techdoc theme, for example, reacts to Category, Priority and Status.

After the properties, leave an empty line and write the title as a level 1 heading. Every document needs exactly this one # heading:

# Check last night's backups

The title comes from this line. A Title: property is ignored.

Use ## for sections and ### for subsections. Themes use them for the table of contents, and techdoc lets readers fold them.

## Steps

### On the primary server

Link to the Markdown file; KB4IT rewrites the link to the published page:

See [the restore procedure](restore-postgresql.md#steps).

If the target does not exist, the build warns with LINK_BROKEN and names both documents.

Start a line with !!!, a type and an optional title, and indent the text by four spaces:

!!! warning "Stop the application first"
    The restore replaces every table in the database.

Common types are note, tip, important, warning and danger.

Fence code with three backticks and name the language:

```bash
pg_restore -d appdb appdb.dump
```

Fence the diagram source with mermaid:

```mermaid
flowchart LR
    Source --> Build --> Site
```

The reader sees a drawing instead of the text:

flowchart LR
    Source --> Build --> Site

Mermaid draws flowcharts, sequence diagrams and more; its documentation lists the types, and the gallery has more examples. A diagram with an error shows Mermaid's message in its place, and the build goes on. The drawing uses dark colours when the page background is dark (for example apphelp in dark mode), and light colours otherwise, as the page looks when it loads.

Put TeX between single dollar signs inside a sentence, or between double dollar signs for a block:

The area is $A = \pi r^2$.

$$
\int_0^1 x^2\,dx = \frac{1}{3}
$$

The reader sees:

The area is A = \pi r^2.

The gallery shows matrices, aligned equations and more. A formula KaTeX cannot read shows its source in red, and the build goes on. To write a dollar sign as text, use \$. Rules and limits: formulas.

Put images in source/resources/images/. KB4IT copies source/resources/ to the website as it is, so link to them like this:

![Backup report](resources/images/backup-report.png)

Build the site, or check the documents without building:

kb4it verify ~/mykb/config/repo.json

It lists every document KB4IT cannot read and why. Document format explains each reason.