Code block

A code block holds text that has to be exactly right: a command to run, part of a program, a setting to paste into a file. It is set in a fixed-width font, colored to suit its language, keeps every space and line break as typed, and has a Copy button so readers can take it without missing a character.

Insert it

Type the command at the start of an empty line, press Enter, then type or paste the code. Or choose + on the toolbar, then Code block. If you select text first and use the + menu, that text becomes the code.

• Markdown: three backticks, ```, at the start of a line, then Enter. Add the language straight after them, such as ```python, and the block starts in that language.

• Keyboard: Ctrl+Alt+C (⌘+Option+C on a Mac).

• Code inside a sentence, such as a file name, is inline code (Ctrl+E) instead: see Text formatting.

Languages, and when to use each

Choose the language from the menu at the top left of the block. It colors the code the way that language is usually shown, and readers see its name as a label, so they know what they are looking at. The languages are Plain text, JavaScript, TypeScript, Python, C#, Bash / Shell, JSON, YAML, SQL, HTML, CSS, Go, Rust, Java, Dockerfile and Markdown. One more, Mermaid diagram, draws a diagram instead: see Diagram (Mermaid).

Commands to run: Bash / Shell

cd ~/Downloads
ls -l *.pdf

Commands someone types into Terminal or a command prompt. Put each command on its own line, and say in the text around it which computer to run it on.

A program: Python, JavaScript and the rest

def greet(name):
    return f"Hello, {name}!"

print(greet("Mei"))

A few lines of a program. Keep it to the lines that matter, and say what it does in a sentence before it.

Settings and data: JSON and YAML

{
  "name": "Kestrel Sync",
  "version": "2.0.0",
  "offline": true
}

name: Kestrel Sync
version: 2.0.0
offline: true

A settings file or data to copy. The colors make a missing quotation mark or comma easier to spot.

A query: SQL

SELECT name, email
FROM customers
WHERE plan = 'team'
ORDER BY name;

A database query to run or to review. Put each part of the query on its own line, as here, so it can be read at a glance.

Plain text

2026-09-24 09:14:02  Import started
2026-09-24 09:14:09  3 pictures were too large and were skipped
2026-09-24 09:14:11  Import finished

Text that must stay exact but is not code: log lines, an error message to search for, output to compare against. Plain text is not colored.

With line numbers

const settings = {
  retries: 3,
  timeout: 30,
  offline: true,
}

export default settings

Choose # at the top right of a block, while you edit, to number its lines; readers see the numbers too. Use them when the text refers to lines (line 3 sets the timeout, in seconds) or when the block is long. Copy takes only the code, never the numbers.

Changing and removing a code block

While you edit, the bar at the top of the block has:

• The language menu, at the left.

• #, which turns line numbers on and off.

• Copy, which copies the code. Readers have this button too.

Inside a code block, Enter starts a new line of code, and Tab does not indent: type spaces instead. To leave the block, press Enter three times at the end, or the down arrow on the last line. To turn it back into normal text, put the cursor in it and press Ctrl+Alt+C.

Good practice

• Always choose the language. Readers get the colors and a label saying what it is.

• Never put a password or a key in a code block. Anyone who can read the page can copy it. Write a placeholder, such as your-api-key, and say where the real one is kept.

• Keep it short. Show the lines that matter and link to the whole file.

• Hide long output in an Expand, with a sentence above it saying what it shows.

Related elements

• Diagram (Mermaid) is a code block that draws a diagram from its text.

• Expand tucks a long log or listing away.

• Blockquote for quoting words rather than code.