Markdown — Structure in Plain Text
Nightjar's first docs lived in a word-processor file that got emailed around. Every time someone pasted it into the website, the headings turned into bold text, the numbered lists restarted at 1 and the commands picked up curly quotes that broke them. Most software documentation today is written in Markdown instead: plain text with a few symbols that mark structure, which a docs site turns into web pages.
The rule
Mark what each piece of text is; the site decides how it looks.
Markdown is about meaning, not appearance. You say "this is a heading" or "this is a step", and the site's design decides fonts and colours. Here is a short Nightjar page:
# Add a monitor
Nightjar checks a URL on a schedule and alerts you when it fails.
## Before you start
- A Nightjar account
- The Nightjar command-line tool, logged in
## Steps
1. Open **Monitors** and select **Add monitor**.
2. Paste your site's address, including `https://`.
3. Choose how often to check, then select **Save**.
Next, [choose where alerts go](alert-channels.md).What each mark means:
#,##,###are headings at levels 1, 2 and 3. Use one level-1 title per page and never skip a level.-starts a bullet list;1.starts a numbered list.**double asterisks**make bold text, which many style guides reserve for interface labels such as Save.- Backticks mark literal text the reader types or sees exactly, such as
https://or a command. [link text](address)makes a link.- A longer code sample goes between two lines of three backticks, with the language named after the first. Every command sample in this course is written that way.
Because it is plain text, Markdown can live in a code repository, be reviewed line by line and be compared version to version.
The shortcut
Read it raw. Good Markdown is readable before it is rendered. Then check four things: one level-1 title, no skipped heading levels, numbers for anything in order, and backticks around anything typed exactly.
The notes
"ADD A MONITOR (in big bold) / need an account / type the url with https / pick interval / save"
The trap is formatting for looks: bold lines pretending to be headings, or jumping from # to ### because the smaller text looks nicer. Screen readers, tables of contents and search all rely on real structure.
Drills
Answer fast — trust the rule.
Which line makes a second-level heading?
How do you write a link to the alert channels page?
A page has a # title, then jumps straight to a ### heading. What is wrong?
Which of these belongs in backticks?
Why write steps as a numbered list rather than a bulleted one?
Remember
- Mark what each piece of text is; the site decides how it looks.
- Shortcut: read it raw, then check one title, no skipped levels, numbers for order and backticks for literal text.
- Trap: formatting for looks, such as bold lines posing as headings.