Alert boxes
Alert boxes are titled, coloured panels for the things a reader mustn't miss: a tip, a success, a warning or an error. This page covers inserting them, changing their type and what they can hold.
The four types
| Type | Use it for |
|---|---|
| Info | Background, notes and context |
| Success | Confirmations and things that went right |
| Warning | Something to be careful about |
| Error | Something that will break or must not be done |
Each type has its own colour and icon.
Insert an alert box
- Type
/at the start of a line and choose Info box, Success box, Warning box or Error box. - Or click Alert box on the toolbar, which inserts an Info box.
If your cursor is on an empty line, the box replaces it. Otherwise it goes in below the current block. The cursor lands in the box's title.
Write in an alert box
A box has two parts:
- Title: one line. The placeholder reads Title.
- Description: the text underneath. The placeholder reads Description.
Inside a box:
| Key | What it does |
|---|---|
| Enter in the title | Moves to the description. |
| Enter in the description | Starts a new line of description. |
| Enter twice at the end | Leaves the box and starts a new paragraph below it. |
| Tab / Shift Tab | Moves forwards or backwards through the title and the lines of the description, and out of the box. |
| Backspace at the start of an empty title | Removes the box, if its description is empty too. |
Change the type
Click inside the box. A row of four icons appears on the box: Info, Success, Warning and Error. Click one to switch. The icons are hidden again when your cursor leaves the box.
What a box can hold
Alert boxes are kept simple on purpose:
- Text only. The description holds paragraphs of text, with bold, italic, strikethrough, inline code and links. Headings, lists, code blocks, tables and images can't go inside, so those toolbar buttons are off while your cursor is in a box. An image you drop or upload while in a box is placed just after it.
- Top level only. A box can't go inside a list, a quote, a table or another box. Alert box is greyed out when your cursor is somewhere a box can't go.
- No alignment. Text in a box is always left-aligned.
To move a box, drag it by its icon.
Alert boxes elsewhere
- Export as Markdown writes each box in GitHub's alert format, so it renders as an alert on GitHub: Info as
[!NOTE], Success as[!TIP], Warning as[!WARNING]and Error as[!CAUTION]. The title becomes a bold first line. - Search covers the title and description.
- When you're editing together, a box someone else is working in is locked for you, with a note saying who's editing it.