Skip to content

Style guide

Voice

  • Plain, international English; address the reader as "you"; present tense.
  • Use upstream terminology (for example "nftables table, chain and rule").
  • Match the voice of the page type: guiding in tutorials ("Now run…", "Notice that…"), direct and imperative in how-to guides, neutral in reference, discursive in explanation.

Markdown

  • One H1 per page, matching the title in front matter.
  • Write one sentence per line where practical; it keeps diffs readable.
  • Every fenced code block declares a language: bash, console, ini, yaml, toml, text, and so on.
  • Use console to show commands and their output, with a $ prompt for an unprivileged user and # for root. Use bash for commands meant to be copied as they are.
  • Write placeholders in angle brackets and upper case, such as <INTERFACE>, and explain each one once per page.
  • Indent content inside list items by 4 spaces (Python-Markdown requires it).
  • Draw diagrams in Mermaid, or as SVG with its source committed.

Examples must be safe and fictional

  • IPv4: 192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24 (RFC 5737). IPv6: 2001:db8::/32 (RFC 3849).
  • Domains: example.com, example.net, example.org.
  • Never include real hostnames, addresses, keys or other secrets.

Warnings

  • !!! warning for anything that can lose data or lock you out, for example changing firewall rules over SSH.
  • !!! note for useful side information; !!! tip sparingly.
  • Precede every destructive command with a warning and, where possible, a verification or rollback step.

Distribution differences

How-to guides and reference pages use content tabs, always in this order and with these exact labels, so a reader's choice is remembered across pages:

=== "Debian/Ubuntu"

=== "RHEL/Alma/Rocky"

=== "Arch"

=== "Gentoo"
  • If the steps are identical on every distribution, use one block without tabs.
  • In the Gentoo tab, give the OpenRC command first. Where the systemd profile differs, you may give its command too, marked as not verified.
  • The RHEL/Alma/Rocky tab is verified on AlmaLinux 10 and Rocky Linux 10 and applies to RHEL 10.
  • Supported targets are listed in scripts/taxonomy.toml and recorded in ADR-005. Ubuntu 24.04 and Fedora are not supported.
  • If a task doesn't apply to a distribution, say so in its tab and link to the nearest alternative.
  • Tutorials use a single distribution and don't use distribution tabs.
  • Cloud images aren't standard installs. The labs boot each distribution's official cloud image, whose defaults can differ from an installed system (for example, Debian's cloud image configures networks with netplan, a debian-installer server with ifupdown). When a step depends on such a default, say which installations it applies to and how readers can tell which case they're in, and cover the other common case where you can.

Front matter

Every page inside tutorials/, how-to/, reference/ or explanation/ (other than index.md) needs:

---
title: How to extend an LVM logical volume online
description: Grow an ext4 or XFS filesystem on LVM without unmounting it.
type: how-to            # tutorial | how-to | reference | explanation; must match the folder
domain: storage         # a domain from scripts/taxonomy.toml; must match the sub-folder
tags: [lvm, ext4, xfs]
distros: [debian-13, ubuntu-26.04, almalinux-10, rocky-10, arch@2026-11-01, gentoo-openrc@2026-11-01]
verified: 2026-11-01    # the date the commands were last verified
owner: "@jaredrowling"   # the maintainer responsible for keeping it current
status: draft           # draft | stable | deprecated
weight: 10              # optional: order within its domain (lower first; default 100)
---

Navigation and section landing pages are generated from front matter: run make nav after adding a page or changing its title, description, domain or weight.

Point-release distributions use a version (debian-13). Rolling releases use the date of the lab snapshot the page was checked against (arch@2026-11-01; see scripts/lab.py list), never the date the page was written. make frontmatter checks all of this.

Original text

Write in your own words and link to sources. Don't copy text from man pages, upstream documentation or other wikis beyond short quotations with a citation. Arch Wiki text (GFDL) is incompatible with our licence and must never be copied.