GitHub-style alerts are easy to add and easy to overuse. In a browser preview they add colour and an icon; on a printed page they consume space, and the colour may disappear. The useful question is not "can this be an alert?" but "does this sentence change what the reader does next?"
What the converter supports
Markdown to PDF lists GitHub alerts among its features, and its public product notes name the > [!NOTE], TIP, IMPORTANT, WARNING and CAUTION forms. In a desktop browser check on 24 October 2026, all five rendered as labelled callout boxes, and a one-page PDF export kept the label, icon and colour for each one. The same export in greyscale kept the labels and icons while dropping the colour difference. That is one export, not a claim about every viewer or printer.
The syntax is a blockquote with a marker
An alert is a blockquote whose first line is the type marker, followed by the alert text, each line prefixed with >. The converter follows the GitHub spelling: an uppercase type inside square brackets, then the content as a normal blockquote.
> [!WARNING]
> This step deletes the previous export.
>
> Keep a copy until the review is signed off.
GitHub's own documentation defines five types, each with a different job: NOTE for useful information, TIP for advice, IMPORTANT for key information, WARNING for urgent attention and CAUTION for risk of a negative outcome. Copying those roles is more useful than choosing a colour you like. The same documentation advises against placing alerts consecutively and says alerts cannot be nested within other elements.
What the checks showed
- Five consecutive alerts all rendered with their own label and icon, so the syntax works in sequence even though GitHub advises against stacking them.
- A lowercase
[!note]marker stayed literal text, and an unsupported[!ERROR]marker did too. The type name must be one of the five, in uppercase. - Writing
> [!NOTE] Same line text.produced a Note callout whose body was "Same line text." The marker is separated from the body, not treated as part of the sentence. - An alert placed inside a list item rendered in the preview, even though GitHub's documentation says alerts cannot be nested within other elements. Treat top-level placement as the portable choice.
- Lists, a fenced code block and a small table inside a single alert all rendered inside the callout. That works, but a callout containing a table is usually doing too much.
Choose alerts by consequence, not emphasis
- Use NOTE for context the reader can skip. It is the weakest signal and the safest default. If the sentence merely helps, it does not need to interrupt the page.
- Use TIP for a better way to do the task. A tip should change the method, not repeat the instruction in friendlier words.
- Use IMPORTANT for a fact the reader must know to succeed. A missing prerequisite or a limit of the tool belongs here.
- Use WARNING when ignoring the sentence causes a problem now. Data loss, an irreversible step or a failed upload are warning material.
- Use CAUTION for risk with a negative outcome. Reserve it for actions that could affect production, money, privacy or safety. If a page has three cautions, the reader has no way to rank them.
A practical editorial budget is one alert per section, and rarely more than one per printed page. That is a writing guideline, not a product limit. It follows from the page: each callout adds padding, a rule and a label, so a document with an alert after every paragraph becomes harder to scan than the same text without them.
Write the label and the first line together
The label ("Warning", "Caution") is generic. The first sentence has to carry the specific consequence: "This deletes the previous export" is useful; "Be careful" is not. Put the action and its object in that sentence, then use the rest of the callout for the condition or the recovery step.
Keep one idea per alert. If the callout needs a list, a table and a code sample, it is probably a subsection with a heading. On paper, that subsection can break across pages in a controlled way; a single callout cannot be relied on to stay together.
Check the callout in the PDF
- Print or preview in greyscale. The label and icon should still identify the alert. In the test export they did, which means the words carry the meaning even when the border colour is lost.
- Look at page boundaries. A callout near the bottom of a page may be split or pushed forward. Check that its label is not stranded from its body.
- Read at 100%. Alert text is often smaller than body text. If the warning is hard to read at normal size, shorten it rather than shrinking the page.
- Select the alert text. Confirm the label and body extract as text, not as an image. This does not certify accessibility, but it catches a callout that was flattened during export.
- Count the alerts on the page. If more than one competes for attention, demote the weakest to ordinary prose.
Diagnose an alert that did not render
- The marker appears as literal text
- Check the spelling and case of the type, the square brackets, and the leading
>on every line.[!note]and[!ERROR]both stayed literal in the check. - The alert swallowed the next paragraph
- The content continues until the blockquote ends. Add a blank line and start the next paragraph without a
>prefix. - The first sentence disappeared into the title
- Keep the marker on its own line. Text written after the marker becomes the body, which is workable but easy to misread in the source.
- The callout looks cramped in print
- Shorten the body, remove nested blocks, or convert the content to a short subsection with a heading. A warning that needs a table is a section, not a callout.
- Every page has a coloured box
- Demote most of them. Use NOTE only where the reader benefits from skipping, and keep WARNING and CAUTION for consequences that actually change behaviour.
Delivery checklist
- Each alert earns its place by changing what the reader does, not by adding emphasis.
- The type is the weakest one that fits; CAUTION is not used for ordinary tidiness advice.
- Marker on its own line, uppercase, with
>on every line of the body. - One idea per callout; no alert containing a table, a list and a code block at once.
- Greyscale print checked; label and icon still identify the alert.
- Page boundaries checked so the label stays with its body.
- Repeated alerts across the document reviewed and most of them demoted.
Sources and scope
Checked 24 October 2026. The guidance is editorial judgement, not a product rule. Observations come from one desktop browser session and a one-page PDF export on that date; no cross-viewer, printer or accessibility audit is claimed.
- GitHub Docs: Alerts — the five types, their intended meanings, the blockquote syntax, the advice against consecutive alerts and the note that alerts cannot be nested.
- Markdown to PDF: product notes — GitHub alert support and browser-side handling, as described by the product.
- Markdown to PDF homepage — current feature list.