Skip to content

Editing this site

The whole site is Markdown files in one public repository. There is no admin login, no database and no build step you have to run: you change a file, and a GitHub Action rebuilds and publishes the site within about a minute.

From a phone

This is the intended way to work day to day.

  1. Open any page on the site and tap the pencil icon in the top right. It opens exactly that file in the GitHub editor.
  2. Write. The editor is plain text — Markdown, no formatting toolbar needed.
  3. Scroll down, write a short line describing the change, and tap Commit changes.
  4. Wait about a minute. The site is updated.

The GitHub mobile app works too, and is more comfortable for longer edits: open the repository, browse to docs/, pick the file, tap the pencil.

Editing without breaking anything

You cannot break the published site by writing bad Markdown — the worst case is that a page renders oddly and you fix it with another commit. The only change that can stop the build is a broken mkdocs.yml.

Adding a new page

  1. In the GitHub editor, create a file under docs/ — for example docs/documentation/new-topic.md. Its name becomes part of the URL.
  2. Start the file with a single # Title line.
  3. Add it to the nav: list in mkdocs.yml, otherwise the page is published but not linked from the menu.

Markdown you will actually use

# Page title
## Section

Plain paragraph text. **Bold**, *italic*, and a [link](https://example.com).

- bullet
- another bullet

1. numbered
2. list

> A quote.

`inline code`

Admonitions are a Material feature and are worth knowing — they draw the coloured boxes used across this site:

!!! note "Optional title"
    Indented body text.

Available types include note, tip, warning, danger, example.

From a computer

Clone the repository, then:

pip install -r requirements.txt
mkdocs serve

That serves the site at http://127.0.0.1:8000/ and reloads on every save. Commit and push when you are happy — the same Action publishes it.

Where things are

Path What it is
docs/ Every page of the site, as Markdown.
mkdocs.yml Site configuration and the navigation menu.
docs/CNAME The custom domain, kept beside the content. The domain that actually counts is the one in Settings → Pages; keep the two the same.
.github/workflows/deploy.yml The Action that builds and publishes.
requirements.txt The exact theme version the site is built with.

When something goes wrong

Open the Actions tab in the repository. A red mark means the build failed; the log says which file and line. The previously published site stays online until a build succeeds, so a failed build never takes the site down.