Style guide: how our release notes look
Every element a release note, incident report or post here can use, written the way David and I write them.
David asked for one page that shows how everything looks before he writes the next incident report. This is it. Each heading names the element below it.
Heading level two
Release sections such as Added and Fixed, and the parts of an incident report. They fill the table of contents.
Heading level three
A step inside a section, such as one config key. Indented in the table of contents.
Heading level four
Rare. Used once, for the two kinds of probe token.
Heading level five
Not used yet.
Heading level six
Not used yet either, but it has a size.
Paragraph with inline formats
An alert fires when two probes agree, not one, and the PEGEL_CONFIG variable is gone. Write keys as interval = 60. The probe list is ordered, p95 stays under 70 ms from home, 24 checks a minute is our own load, and false alarms went from 121 to 1. More in why an alert needs two probes.
Bulleted list
- One binary, no database server.
- Configured in
pegel.toml. - A release every few weeks, notes on this site.
Numbered list
- Stop Pegel.
- Multiply every
intervalby 60. - Run
pegel check, then start it again.
Blockquote
A monitor that cries wolf every night is a monitor nobody reads in the morning.
Aside quote
David’s rule for incident reports: the timeline first, the reasons second, names never.
Code block with a file name
func Down(results []probe.Result, agree int) bool {
failed := 0
for _, r := range results {
if !r.OK {
failed++
}
}
return failed >= agree
}Terminal
$ pegel version
pegel 0.9.0 linux/arm64
$ pegel check --config pegel.toml
ok shop 200 41 ms home + vpsDiff
[defaults]
-interval = 1
+interval = 60Marked, added and removed lines
[defaults]
interval = 60 # [!code highlight]
timeout = 30 # [!code --]
timeout = 10 # [!code ++]Tabs
$ curl -LO https://pegel.example.org/download/pegel_0.9.1_linux_amd64.tar.gz$ curl -LO https://pegel.example.org/download/pegel_0.9.1_linux_arm64.tar.gz$ go install pegel.example.org/pegel/cmd/[email protected]Long block, folded
[defaults]
interval = 60
timeout = 10
agree = 2
[notify]
mail = ["[email protected]"]
webhook = "https://hooks.example.com/pegel"
[status]
title = "Pegel status"
checks = ["site", "downloads"]
[[check]]
name = "site"
url = "https://pegel.example.org/"
expect = 200
[[check]]
name = "downloads"
url = "https://pegel.example.org/download/"
expect = 200
[[probe]]
name = "home"
[[probe]]
name = "vps"Wrapped lines
[[check]]
name = "shop"
url = "https://shop.example.org/health?probe=pegel&expect=ok®ion=nordtal&timeout=10s&verbose=false"Code with a caption
$ pegel check --config pegel.tomlHorizontal rule
Separates a postscript from the release notes.
Image, regular width

Image with a link

Image, wide

Image, full width

Gallery with two images


Gallery with three images



Callouts
Note, tip, warning and danger take the colours of the code. In a release note, the red one is the breaking change. The others follow Ghost’s callout colours.
agree defaults to 2 when there are two probes or more, and to 1 otherwise.interval counts seconds since 0.9.0. Multiply every value by 60 before you upgrade.Toggle
Why Go?
One static binary per architecture, and a standard library that covers HTTP, TLS and timers. Pegel has four dependencies.
Does it need a database?
No. History is kept in files under /var/lib/pegel, 90 days by default.
Bookmark

A second bookmark

Button
Button, centred
Header card
Header card, split with image

Header card, centred
121 false alarms
From one probe, May to October. Two probes sent one.
Signup card
Call to action
Pegel’s site, downloads and second probe cost 14 euros a month. Sponsors pay for them.
Call to action for members
Only members see the card under this heading. Sign in and it shows up here.
Product
The Raspberry Pi in the hallway
Four cores, 4 GB, a USB disk for the history. It runs Pegel for 40 sites at 23 MB of memory.
Audio
Video
Looping video
File
Embed
pegel.example.org: all checks green for 17 days.
HTML card with a table
| Release | Date |
|---|---|
| v0.8.0 | 2026-08-24 |
| v0.8.2 | 2026-10-05 |
| v0.9.0 | 2026-11-09 |
Markdown card with a table
| Command | What it does |
|---|---|
pegel check |
reads the config, runs each check once |
pegel probe |
runs checks for another Pegel |
Typesetting
The first paragraph of a post is set larger. These posts show the other variants:
- The home probe is slower, and we kept it opens with a drop cap.
- What comes after 0.9.0 opens with small capitals.
- Running Pegel on a Raspberry Pi is set justified.
- Why an alert needs two probes has no larger first paragraph.
Members pages
Readers who sign up meet four pages: Sign up, Sign in, Account and Pricing.
subscribe
New entries and the next chapter by mail, nothing else.

