Code Block in Confluence: Cloud and Data Center Guide
November 11, 2026 · 9 min read
Code Block in Confluence: Insert, Format, and Pick a Language
To add a code block in Confluence Cloud, type three backticks and press Space, or type /code. The Format text menu works too. You get a code snippet with a language picker, line numbers and wrapping. Data Center uses the older Code Block macro, which adds a title, a collapse option and 80+ languages.
Search results still surface Atlassian's old macro page, even though Cloud now gives you the snippet element instead. This guide splits the two editions, then covers wiki markup, collapsing, and drafting code-heavy pages in Markdown before they reach Confluence.
How Do You Add a Code Block in Confluence Cloud?
The Cloud editor calls it a code snippet element. Atlassian's insert elements guide and its keyboard shortcut page document four ways to create one:
- Type three backticks, then press Space.
- Type
/codeand choose the code element from the slash menu. - Open the Format text menu in the main toolbar and select Code.
- Press Ctrl+Shift+M on Windows or Cmd+Shift+M on a Mac.
We prefer to create the empty snippet first and paste into it. That's the order Atlassian's auto-detect steps assume, and it keeps your code out of a normal paragraph, where it would pick up body text formatting.
Picking a Language: Auto-Detect and the Language Picker
New snippets detect the language for you. Detection covers 12 languages: CSS, Go, HTML, Java, JavaScript, JSON, Python, Ruby, Rust, Shell, SQL and TypeScript. The picker shows the guess with a "(detected)" label next to it, so you can tell a guess from a choice.
Once you pick a language by hand, detection switches off for that block. The picker also keeps your three most recently used languages at the top of the list, which saves scrolling on pages that mix Python and SQL.
We set the language manually for shell commands and config files. A two-line curl call or a short YAML file gives the detector very little to work with, and YAML isn't on the auto-detect list at all.
Line Numbers, Wrapping, and the Format Button
Click inside a snippet and its toolbar appears. Hide line numbers and Show line numbers toggle the gutter. New snippets wrap long lines by default. A wrap change made in edit mode is saved with the page, while a change a reader makes in view mode resets when the page reloads.
The Format button tidies spacing and indentation, but only for JavaScript/JSX, JSON and SQL. It's disabled for every other language. Take this one-line JSON:
{"service":"billing","replicas":3,"regions":["eu-west-1","us-east-1"]}
With the snippet set to JSON, select Format and Confluence cleans up its spacing and indentation. If the code has a syntax error, such as a missing comma, Confluence shows an error flag and leaves the content unchanged.
Inline Code Versus a Code Snippet
Not every bit of code needs a block. Type a command, flag or file name such as config.yaml between single backticks mid-sentence, and the editor turns it into inline code. Use a snippet when the code spans more than one line or when readers will copy it.
The shortcuts overlap in a confusing way. Atlassian's shortcut page lists Ctrl+Shift+M for both block and inline Code on Windows. On a Mac it lists Cmd+Shift+M for the block and Opt+Shift+M for inline text, so try the other one if nothing happens.
The Code Block Macro in Confluence Data Center
Data Center keeps the classic macro. Per the Code Block Macro page for Data Center 11.0, go to Insert > Other Macros, find Code Block under Formatting, set the options and select Insert. You can also type { or / followed by the start of the macro name.
| Option | Parameter | Default | What it does |
|---|---|---|---|
| Syntax highlighting | language | plain text | Sets the highlighting language |
| Title | title | none | Adds a header above the code |
| Collapsible | collapse | false | Hides the code until a reader expands it |
| Show line numbers | linenumbers | false | Numbers each line |
| First line number | firstline | 1 | Starts the count at another number |
| Turn on wrap | none | false | Wraps long lines; readers can toggle it |
| Copy as text | none | none | Copies the code as plain text |
The macro supports more than 80 languages, and the Confluence 9.1 release notes call out Rust and YAML among them. Uploaded custom languages were removed in 9.0. Admins set a site-wide default under Administration > General Configuration > Configure Code Macro. That default applies to new blocks only, and existing blocks keep their language.
Writing the Code Macro in Wiki Markup
Atlassian documents a wiki markup form of the macro for Data Center, where it's listed as another way to add it. The Cloud macro page shows the same syntax, but it belonged to the legacy editor, so in Cloud you'll mostly meet it in old exports. Every parameter goes after a colon, separated by pipes:
{code:title=retry.py|linenumbers=true|language=python|firstline=12|collapse=true}
for attempt in range(3):
if send(payload):
break
{code}
This renders a block titled retry.py, collapsed on page load, with Python highlighting and line numbers starting at 12. The closest Markdown equivalent is a fence of three backticks with python as its language tag:
for attempt in range(3):
if send(payload):
break
The title, collapse and line number settings have no Markdown counterpart, so they drop out. The Markdown code block guide covers fence syntax in full. To turn a whole page of wiki markup into Markdown, paste it into the Confluence to Markdown converter, which runs in your browser, then check each fence's language tag.
Can You Make a Confluence Code Block Collapsible?
In Data Center, yes: set collapse=true and readers see an "expand source" link instead of the code. Atlassian's snippet documentation lists no collapse setting for Cloud. When Atlassian closed the collapsible snippets request in April 2026, its advice for new pages was to put a code snippet inside an Expand element.
That workaround is simple. Insert an Expand element, give it a title such as "Full nginx config", then add the snippet inside it. Readers click the title to open it. One user comment on that ticket, from July 2026, reports a collapse caret appearing on long snippets, so check your own site first.
Here's the limitation you'll hit next: you can't highlight specific lines inside a Cloud snippet. The documented options don't include it, and Atlassian closed the line highlighting request (CONFCLOUD-37494) as Won't Do. Call out the important line in the text above the block or add a comment in the code. A snippet won't render Mermaid code either, so a Mermaid diagram in Confluence needs an app or an image.
What Happened to Code Block Macros on Legacy Cloud Pages
Atlassian phased out the legacy Cloud editor in stages. Per its deprecation FAQ, automatic conversion of legacy pages rolled out between January 21 and February 18, 2026. The legacy editor was fully retired on April 1, 2026. So if an old tutorial tells you to insert the Code Block macro in Cloud, use the snippet instead.
The old Cloud macro defaulted to Java and offered themes such as Midnight, Eclipse and FadeToGrey. The snippet element's documentation lists no theme setting, so don't expect a page's old dark theme to survive as an option.
According to Atlassian's March 2026 update on the collapsible snippets request, most collapsible blocks on pages converted from March 2, 2026 become an Expand wrapping a snippet. If you're leaving Confluence instead, the Confluence export guide explains how code macros come out the other side.
Drafting Code-Heavy Pages in Markdown Before Pasting
Runbooks and API pages are easier to write in plain text first. In our Markdown editor, the Code Block toolbar button or Ctrl+E (Cmd+E on a Mac) inserts a fenced block. Add bash after the opening backticks and a runbook step looks like this:
kubectl rollout restart deployment/billing
kubectl rollout status deployment/billing
The preview shows that fence as a monospace block with no colour, because our preview doesn't do syntax highlighting. When you move the draft into Confluence, Atlassian documents the backtick shortcut for typing, not for pasting. Test a pasted fence on a scratch page first. The Confluence Markdown guide compares the paste routes that keep formatting. If the snippet is also headed for other tools, see the code block in Word and Google Docs code block guides.
A code block in Confluence comes down to your edition: the snippet element in Cloud, the Code Block macro in Data Center. Pick the language by hand when detection guesses wrong, and wrap long snippets in an Expand element. For pages full of commands, draft them in the editor first, then move the finished text into Confluence and check each block.