Coming soon. The Wiki is in active development, so features and these docs may still change. Early adopters: contact us for access.

Blocks and macros

Panels, expands, decisions, status, anchors, excerpts and includes, page properties, child pages, page trees, recently updated, video, spreadsheet tables, Mermaid diagrams, HTML blocks and plugin blocks

1. Overview

Besides text, a page can hold blocks: boxes that stand out, blocks that show other pages, videos, spreadsheet tables and blocks from plugins. Insert any of them from the "/" menu in the editor. To change one later, select it and choose Block settings in the toolbar. Pages imported from Confluence get these blocks for the macros they used; see Import and export.

2. Boxes: panels, expand, decision

An info panel, a note panel, a code block, a closed expand, a decision, an open question and a tip
An info panel, a note panel, a code block, a closed expand, a decision, an open question and a tip
BlockWhat it doesExample
Info panel / Warning panelA coloured box around text. Its Type can be Info, Note, Warning, Tip or Success, with an optional Title.A Before you start info panel at the top of a runbook.
ExpandA section readers click to open. Its title defaults to Show more; Open by default shows it open.What the verify step checks, with details most readers skip.
DecisionRecords a Decision or an Open question, each with its own colour.Decision: we fail over to the standby region rather than restoring from backup.

Remove box, keep content in a box's settings takes the box away and leaves its text on the page.

3. Status

A small coloured label inside a line of text. Enter its Text and pick a Colour: grey, blue, green, yellow, red or purple. Example: APPROVED in green next to Current state.

4. Anchor

An invisible mark you can link to. Give it a Name (letters, digits, - and _, up to 64); link to it by adding # and the name to the page's address. Headings have anchors of their own already.

5. Code block

Code in a fixed-width font. Its settings add a File name above it and Line numbers. Example: failover.sh with four numbered lines.

6. Excerpt and Include excerpt

An Excerpt marks part of a page so other pages can show it. Give it an optional Name when a page has more than one. Hide on this page shows it only where it is included.

Include excerpt shows another page's excerpt: paste the page's Page link from the address bar and, if needed, the Excerpt name. It shows Excerpt from <page> and always shows the current published text. Example: the overview of a team's area quotes the first lines of its failover runbook.

A hidden excerpt isn't private: it still shows where other pages include it, and in search and page history.

7. Include page

Shows the whole published content of another page, by its Page link. A page can't include itself, and blocks that show other pages aren't shown inside an included page.

8. Page properties and Page properties report

Page properties holds a two-column table of facts about the page (owner, tier, on-call). Give it an optional Name when a page has more than one.

Page properties report gathers those tables into one: for each published page in the space with a given Label, one row, with a column per property. Example: a Services report on the team's overview lists every page labelled service with its Owner, Tier and On call. A report shows up to 12 columns.

9. Child pages, Page tree, Recently updated

Child pages two levels deep, an included excerpt, a page properties report and a recently updated list
Child pages two levels deep, an included excerpt, a page properties report and a recently updated list
BlockShowsSettings
Child pagesThe pages under this oneLevels: 1 to 3 (default 1)
Page treeThe space's page treeLevels (default 2)
Recently updatedThe space's most recently changed pages, with whenPages to list: 5, 10 or 20 (default 10)

These blocks show each reader only the pages they can see: what you see in the editor may be more than a reader sees. Preview the page to check it. Not every page is listed appears when a list is cut short.

10. Video

Video adds a video from a file or a video site.

  • Upload a file: MP4 or WebM, up to 200 MB. A poster frame is taken from it. Add Subtitles as a WebVTT (.vtt) file up to 512 KB, with its Language (such as en or pt-BR).
  • Link from a video site: paste the link. Only sites your administrator allows can be used (YouTube and Vimeo, or your organization's own video platform), set in Settings → Security → Video sites. If a site is taken off the list later, its videos stop playing.
  • Both take a Caption and a Start at time (m:ss).
An uploaded video with its poster frame and caption
An uploaded video with its poster frame and caption

11. Spreadsheet tables

A Spreadsheet table is a table whose cells can hold formulas. Select a cell and type a value, or a formula starting with =, such as =SUM(B2:B4), in the bar above the table. The bar also sets the cell's Number format (as typed, number, currency, percent or date), its Decimal places and, for currencies, the Currency code.

A spreadsheet table: amounts in euros with a total worked out by a formula
A spreadsheet table: amounts in euros with a total worked out by a formula
  • References are A1-style within the same table: A1 is the first row's first cell. Another table can't be referenced.
  • Values are worked out in the editor as you type and saved with the page, so readers see them at once. Hover over a cell to see its formula.
  • Readers can sort a column and Filter rows for themselves, when the first row is headers and there are no merged cells.
  • Numbers and dates show in each reader's language.
  • Errors show in the cell: #DIV/0!, #VALUE!, #REF!, #NAME? (a function that isn't available), #CIRCULAR! (a formula that reads itself) or #CALC! (too slow to work out).

Functions you can use:

KindFunctions
Sums and countsSUM, AVERAGE, COUNT, COUNTA, COUNTBLANK, MIN, MAX, MEDIAN, PRODUCT, SUMIF, COUNTIF, AVERAGEIF
NumbersROUND, ROUNDUP, ROUNDDOWN, ABS, INT, MOD, POWER, SQRT, CEILING, FLOOR
LogicIF, IFERROR, AND, OR, NOT, TRUE, FALSE, ISBLANK, ISNUMBER, ISTEXT, ISERROR
LookupVLOOKUP, HLOOKUP, INDEX
TextCONCAT, CONCATENATE, LEN, LEFT, RIGHT, MID, UPPER, LOWER, TRIM, TEXT, T
DatesTODAY, DATE, DATEDIF, YEAR, MONTH, DAY, DAYS

A table holds at most 2,000 formulas.

12. Mermaid diagrams

Mermaid diagram draws a diagram from text written in Mermaid syntax: flowcharts, sequence diagrams, class and state diagrams, Gantt charts, pie charts and more. Anyone who edits the page can add one from the "/" menu (type diagram, flowchart or sequence). It starts with a small flowchart to change.

A Mermaid diagram in the editor: its text above, the drawing below
A Mermaid diagram in the editor: its text above, the drawing below
  • Write the diagram's text in the block; the drawing under it follows as you type. Everyone editing the page edits the same text, as in a code block.
  • If the text has a mistake, the block says which line when it can, and keeps showing the last drawing that worked until it is fixed.
  • Add a Caption in the field at the top of the block; readers see it under the drawing.
  • Diagrams are drawn in the reader's theme, light or dark, and redrawn when they switch. Lines that set colours (style, classDef, linkStyle) and %%{init}%% settings are ignored, so every diagram stays readable in every theme.
  • A diagram wider than the page scrolls sideways rather than shrinking its labels until they can't be read.
  • Word, PDF and Markdown downloads show the diagram's text as a code block.
A mistake on line 11: the block names the line and dims the last drawing that worked
A mistake on line 11: the block names the line and dims the last drawing that worked

A page holds up to 50 diagrams, each up to 20,000 characters.

13. HTML blocks

An HTML block runs your own HTML, CSS and JavaScript on a page, such as a status widget that reads your build server. Each block runs in a sandbox: it can't read the Wiki, its cookies or the page around it, and it can reach only the sites your administrator lists.

A page with a Mermaid diagram and an HTML block showing a live release train
A page with a Mermaid diagram and an HTML block showing a live release train

HTML blocks are off until an administrator turns them on:

  1. Open the setting — Go to Settings → Security → HTML blocks (needs settings:write).
  2. Turn them on — Tick Allow HTML blocks.
  3. Choose who adds them — Space admins (in the spaces they manage; recommended) or Installation admins only (space admins can then only move or remove blocks).
  4. List the sites — Under Sites blocks may reach, add each host name blocks may load from or call, such as status.example.com. HTTPS only; up to 20. Everything else is blocked, including the Wiki itself.
  5. Save — Use the page's Save bar.
Settings → Security → HTML blocks: on, space admins add them, one allowed site
Settings → Security → HTML blocks: on, space admins add them, one allowed site

To add a block, type /html in the editor (the item shows only to people who may add blocks), paste the HTML, and press Run preview: the block runs exactly as readers will see it, and any call to a site that isn't allowed is listed under the preview. Set a Height in pixels (60 to 1,200), or leave it empty to fit the content. Save block puts it on the page.

Adding an HTML block: the preview runs, and a call to a site that isn't allowed is listed as blocked
Adding an HTML block: the preview runs, and a call to a site that isn't allowed is listed as blocked
  • Style the block with the theme's colours, such as var(--dx-color-text), var(--dx-color-border) and var(--dx-color-surface): they follow the reader's light or dark theme.
  • Anyone who edits the page can move or remove a block; only people allowed to add blocks can change what it shows (the pencil on the block). Every save is a new block, so an older version of the page keeps showing the HTML it had.
  • Readers see HTML block · sandboxed under it; people who edit the page also see the sites it may reach.
  • Turning the setting off hides every HTML block at once, and taking a site off the list stops it in every block. Visitors who aren't signed in see blocks only on public spaces.
  • A page holds up to 20 HTML blocks, each up to 64 KB. Word and PDF downloads show a note in their place: open the page in the Wiki to see it.
  • Saving a block raises the html_block.create event and changing the setting html_block_settings.update, so a policy can, for example, refuse HTML that loads scripts. See Events.

The sandbox protects the Wiki and its readers, but a block's JavaScript can still send anything it shows or a reader types to the sites you list. Only list sites you trust.

14. Plugin blocks

Plugins can add their own blocks, such as a progress bar or a diagram. While such a plugin is active, its blocks are listed in the "/" menu under their own names; the block is drawn by the plugin, inside the page, and its settings are inside the block.

A plugin block on a page: a progress bar from a sample plugin
A plugin block on a page: a progress bar from a sample plugin
  • If the plugin is turned off or removed, or the licence is below Pro (plugins need Pro), readers see the block's short text description instead, and the block is kept on the page.
  • Visitors who aren't signed in, and pages that include another page, see the text too.
  • A page can hold up to 50 plugin blocks; the first 20 are drawn, the rest show their text.

A macro from another wiki that an import couldn't convert shows as Imported macro, with What it held. You can leave it or replace it with a block.