Add code blocks

Code blocks show commands, settings and code samples in a fixed-width font with syntax highlighting, so developers can read them at a glance. They're the backbone of good API and integration guides.

Add a code block

1. On an empty line, type /code and press Enter. (Typing ``` and a space works too.)

2. Paste or type your code. It's highlighted automatically.

3. To continue with normal text, click below the block or press ⌘Enter (Ctrl+Enter on Windows).

Here's a code block as your readers see it:

function greet(name) {
  return `Hello, ${name}`;
}

Choose the language

A new code block is set to auto and works out the language itself. If the colors look wrong, pick the language from the menu in the top-right corner of the block, for example Bash, JavaScript, JSON, PHP or Python.

Code inside a sentence

For a short command, file name or value in the middle of a sentence, use inline code instead. Select the text and click Inline code in the toolbar, press ⌘E (Ctrl+E on Windows), or type it between backticks, like `npm install`.

Good to know

• Tab inside a code block adds four spaces instead of moving to the next field.

• Anything you paste into a code block stays exactly as it is. Nothing is converted or formatted.

• The formatting toolbar doesn't appear inside a code block.

• Replace real API keys and passwords with placeholders such as YOUR_API_KEY before you publish.

• Give each command its own block, and say in a sentence above it what it does.

Document an API endpoint

For API docs, the API endpoint block (type /api) lays out an endpoint's method, path, parameters, request body and responses. Readers get ready-made code samples in cURL, JavaScript, Python and PHP, each with a Copy button.

Related articles

• Add headings, lists and other blocks

• Create an API key