The article editor builds everything from blocks. Type / at the start of an empty line to open the block menu, then keep typing to filter it: /code finds Code block and Code tabs. Use the arrow keys and Enter to pick one, or Escape to close the menu.

Articles have more blocks than posts and changelog entries: tables, steps, code tabs, file names on code, collapsible sections, a table of contents and file attachments are for articles only.

The block menu: Heading, Subheading, Bulleted list, Numbered list, Quote, Code block, Table, Code tabs, Steps, Collapsible, Table of contents, Divider, Image, Video and File

Format text and add links

Select some text to get the formatting bar: Bold, Italic, Code and Link. A link must start with http://, https:// or mailto:.

Headings, lists, quotes and dividers

  • Heading and Subheading start the article's sections. An article with two or more of them gets "On this page" beside it on wide screens, and the table of contents lists them.

  • Bulleted list and Numbered list.

  • Quote for a note or a warning.

  • Divider for a line across the page.

Tables

Table adds a table of three rows and three columns, the first row a header. With the cursor in it, the bar has Add row, Add column, Delete row, Delete column and Delete table.

Numbered steps

Steps is for a how-to with a clear order. Each step has a short title and its own text.

  1. Choose Steps, and type the first step's title.

  2. Press Enter to write the step's text under it. Type / there to add a bulleted or numbered list, a code block, code tabs, an image or a file.

  3. Press Enter on an empty last line to start the next step.

  4. When you're done, press Enter on the new step's empty title. The cursor moves to a line after the steps.

To join a step to the one before it, put the cursor at the start of its title and press Backspace. Steps can't hold headings, and can't go inside a collapsible section.

Readers see each step with its number in a circle, joined to the next by a line.

Four numbered steps on the portal, each with a bold title and its text, joined by a line

Code, with a file name

Code block shows code as it's typed. Click inside one and choose File name in the bar above it to show a name over the code, such as .env or package.json. Names are one line of up to 80 characters.

Code tabs

Code tabs shows the same step in several versions, such as curl, Node.js and Python, one at a time. Readers pick a tab to see its code.

  • It starts with two tabs, Tab 1 and Tab 2. Click into a tab to type its code. ↓ at the end of one moves to the next.

  • Click inside a tab for its bar: Rename tab, Add tab (up to 8 tabs) and Remove tab. Each tab needs a label.

  • Removing one of the last two tabs turns the other into a code block, with its label as the file name.

  • To leave the tabs, press Enter three times at the end of a tab's code, or ↓ at the end of the last tab.

Code tabs in the editor, with the Rename tab, Add tab and Remove tab bar above them

Collapsible sections

Collapsible shows a line that readers click to open, such as a question with its answer. It's good for FAQs and for detail most readers can skip.

  1. Choose Collapsible and type the summary line.

  2. Press Enter and write what it opens to. It can hold text, lists, quotes, code, code tabs, dividers, images, videos, files and tables, but no headings, steps or another collapsible section.

  3. Press Enter on an empty last line to leave it.

Each collapsible section needs a summary. To remove the block but keep its contents, clear the summary and press Backspace.

Readers see it closed. Docs search and AI answers still find the text inside.

Table of contents

Table of contents lists the article's headings as links, with subheadings under their heading. Readers see it titled In this article.

Add it on a line of its own, not inside a list, quote, table or other block. It follows your headings as you write. Until the article has headings, the editor shows "Table of contents: the headings you add show here." and readers see nothing.

Images and videos

  • Image uploads a JPEG, PNG, WebP or GIF of up to 10 MB. You can also paste or drop images into the text. Select an image for its bar: its width (25%, 50%, 75% or 100% of the column), its alignment (left, centre or right) and Alt text, which describes it for people who can't see it.

  • Video embeds a YouTube, Vimeo or Loom link.

Files

File attaches a document that readers can download, such as a PDF form or a CSV template. You can also paste or drop files into the text. Readers see its type, name and size, and select it to download it.

You can attach PDF, TXT, CSV, Markdown, JSON and ZIP files, Word, Excel and PowerPoint files, and OpenDocument text, spreadsheets and presentations, each up to 25 MB.

A project has 1 GB in all for its images and files. Once it's full, uploads are refused with "This project has no space left".

Wait for uploads to finish before you save. If you save too soon, the editor asks you to wait.