Panels

A panel is a colored box around one or more paragraphs. It tells readers “stop and read this” before they have read a word of it, and its color tells them what kind of thing it is: background, a tip, a warning. Use one for the thing on a page that nobody should miss.

Insert it

Type the command at the start of an empty line and press Enter. Or choose + on the toolbar, then Panels. If you select some text first, either way puts that text inside the new panel.

Typing /info makes a panel; the buttons above it change its type.

The five kinds, and when to use each

Pick the kind by what the text means, not by the color you like: readers learn what each color means, and a warning in a green box reads as good news.

Changing and removing a panel

Click anywhere inside a panel and a small menu appears above it:

• The five colored buttons switch the panel to that kind. Whatever is inside stays as it is.

• Remove panel takes the box away and keeps everything that was in it, as ordinary text.

A panel can hold anything a page can: several paragraphs, lists, tables, pictures, even code. To add another paragraph inside it, press Enter at the end of the last line; press Enter twice on an empty line to step out below the panel.

Good practice

• Use them sparingly. One or two on a page stand out. When every other paragraph is in a box, nothing stands out, and readers learn to skip them.

• Lead with the point. Start with a few words in bold that say what the panel is about, as the examples above do, so someone skimming gets it without reading on.

• Keep one idea to a panel. Two warnings in one box are easy to half-read; two boxes are not.

• Do not stack them. Several panels in a row read as a wall of color. Move the least important into the text.

Related elements

• Expand hides detail most readers can skip behind a title they click to open.

• Decision records a decision the team made, so it can be found later.

• Blockquote sets apart a quotation, rather than something the reader must act on.