How to Add Code Block in Confluence

What Is a Code Block in Confluence — and Why Does It Matter?

If you’ve ever pasted raw code into a Confluence page and watched it turn into an unreadable wall of text, you already know the problem.

Confluence is one of the most widely used team wikis in the world — over 75,000 companies use Atlassian products globally, including Confluence. But without proper formatting, even the best documentation falls apart the moment someone drops a script or API snippet directly into a paragraph.

A code block solves this instantly. It renders code in a monospaced font, preserves indentation, enables syntax highlighting for 40+ programming languages, and prevents Confluence from auto-formatting your content in ways you didn’t ask for.

Whether you’re documenting a deployment process, sharing a SQL query, or writing onboarding docs for your engineering team, knowing how to use the Code Macro correctly is a non-negotiable Confluence skill.

How to Add a Code Block in Confluence (New Editor)

Atlassian rolled out a new editor experience across Confluence Cloud. If you’re on the updated interface, here’s the fastest way to insert a code block.

Using the “/” Command (Fastest Method)

1. Open the Confluence page you want to edit and click Edit
2. Place your cursor where you want the code block to appear
3. Type / to open the insert menu
4. Type code and select Code Block from the dropdown
5. The code block macro will appear inline — paste or type your code directly inside it

That’s it. Three seconds, done.

Using the Insert Menu

1. Click Edit on your Confluence page
2. Click the “+” insert icon in the toolbar (or go to Insert > Other Macros)
3. Search for “Code Block” in the macro browser
4. Click on it to insert

How to Add a Code Block in Confluence (Legacy Editor)

If your team is still on the older Confluence editor (common in Confluence Server or Data Center instances), the process is slightly different.

1. Open the page in edit mode
2. Click Insert in the top menu bar
3. Select Other Macros
4. In the macro browser, search for “Code Block”
5. Click Code Block and then Select
6. Configure your options in the macro dialog (language, theme, line numbers)
7. Click Insert to place it on the page

Configuring the Code Block Macro — All Your Options Explained

Once you insert a code block, a configuration panel appears. Here’s what each setting does and when to use it.

Language (Syntax Highlighting)

This is the most important setting. Choose the programming language your code is written in, and Confluence will apply colour-coded syntax highlighting automatically.

Supported languages include Python, JavaScript, Java, SQL, Bash, XML, JSON, HTML, CSS, Ruby, Scala, and 30+ more. If your language isn’t listed, select None — the code will still appear in a clean monospaced block without highlighting.

Pro tip: Always set the language. Teams that use consistent syntax highlighting report faster code review cycles because readers can parse structure at a glance.

Theme

Confluence offers several display themes for code blocks:

• Default — Light background, standard text
• Django — Dark background (easier on eyes for long code reviews)
• Emacs / FadeToGrey / Midnight / RDark — Other dark variants
• Confluence — Matches the default Confluence page style

For internal documentation shared across mixed audiences (technical and non-technical), Default or Confluence theme tends to create the least friction.

Title

Add an optional title above your code block — useful when a page contains multiple snippets. Examples: “API Request Example,” “Production Config,” “Migration Script v2.”

Line Numbers

Toggle line numbers on if you expect people to reference specific lines in comments or reviews. For short snippets under 10 lines, this is optional. For anything longer — turn it on. It eliminates the “look at line 47” confusion.

Collapse

When enabled, the code block appears collapsed by default — readers click to expand. Use this for long code sections (100+ lines) that would otherwise overwhelm the page visually.

Keyboard Shortcut for Code Blocks

If you’re adding code blocks frequently, skip the menus entirely.

In the new Confluence editor, you can use backtick formatting:

• Type three backticks “` at the start of a line and press Enter — Confluence will automatically convert this into a code block

This mirrors how Markdown works, and it’s significantly faster once you build the habit.

How to Add Inline Code in Confluence

Code blocks are for multi-line code. For a single function name, variable, or command reference inside a sentence, use inline code instead.

In the new editor:

• Highlight the text you want to format as code
• Press Ctrl + Shift + M (Windows) or Cmd + Shift + M (Mac)

This formats the text in a monospaced font inline, so you can write things like “run the deploy.sh script before proceeding” without breaking into a full code block.

Common Mistakes When Adding Code Blocks in Confluence

Pasting code as plain text. The most common mistake. Plain-text code loses indentation, breaks on special characters, and is difficult to read. Always use the Code Macro.

Skipping the language setting. Without syntax highlighting, readers spend more time parsing structure. It takes five seconds to select the right language — always do it.

Using screenshots instead of code blocks. Screenshots of code can’t be copied, searched, or version-controlled. They also break on mobile. If the content is code, use a code block.

Not using the title field on multi-code pages. When a page has five or six code snippets, untitled blocks become confusing fast. Label each one.

Ignoring the collapse option on long snippets. A 200-line code block in the middle of a page destroys readability. Collapse it so the page stays navigable.

Why Teams Document Code in Confluence (The Numbers Tell the Story)

Documentation quality has a measurable impact on team performance. According to research by Atlassian, teams that document processes see a 25% reduction in onboarding time for new team members. A separate study found that employees spend an average of 1.8 hours per day searching for information — proper documentation directly cuts into that waste.

57% of knowledge workers say they can’t find the information they need when they need it (McKinsey). Code blocks in Confluence directly solve one specific slice of this problem: making technical knowledge findable, readable, and reusable.

When technical documentation is formatted clearly — syntax highlighted, titled, and structured — engineers spend less time context-switching and more time building. That’s not a soft benefit. It translates to sprint velocity and shipping speed.

How to Edit or Delete a Code Block in Confluence

To edit: Click on the code block in the editor — a pencil/edit icon will appear above it. Click it to open the macro parameters and change your settings (language, theme, line numbers). To change the code itself, simply click inside the block and type.

To delete: Click on the code block to select it, then press Backspace or Delete. On some versions, you may need to click the block, then use the trash icon that appears in the toolbar above the macro.

Code Blocks vs. Code Panels — What’s the Difference?

Confluence also offers a Panel Macro with colour options, but this is not designed for code. The Panel is for callouts, warnings, and notes — not technical content.

The Code Block Macro is purpose-built for code: monospaced font, syntax highlighting, preserved whitespace, and copy-to-clipboard functionality in newer Confluence versions.

Always use the Code Block Macro for code. Use the Panel Macro for callouts and notices.

Tips for Getting the Most Out of Confluence Code Blocks

Use consistent language tagging across your team. Agree on a standard: if your team writes Python 3, don’t have half your pages tagged “Python” and the other half “Python 3.” Consistency makes searching and referencing faster.

Pair code blocks with context. A code block alone answers “what” — but pair it with a brief explanation above or below and you answer “why.” Teams that include context alongside code snippets reduce the number of follow-up questions in Slack or email by a measurable margin.

Use page templates for recurring code documentation. If your team regularly documents API endpoints, deployment scripts, or config files, build a Confluence template with pre-configured code block macros. According to Atlassian, teams using templates see a 40% reduction in documentation creation time.

Version your code documentation. Confluence has built-in page versioning. When you update a code snippet, note what changed and when — especially for configuration files or scripts that affect production systems.

Test your code blocks on mobile. Roughly 15-20% of internal Confluence usage happens on mobile (Atlassian internal data). Code blocks render correctly on mobile in most Confluence Cloud instances, but long lines can create horizontal scroll. Keep your code blocks below 80 characters per line where possible.

Confluence Code Blocks and Team Productivity — The Bigger Picture

Documentation isn’t just an internal nicety. It directly affects how fast your team moves, how quickly new people ramp up, and how much time gets lost re-explaining things that should have been written down.

85% of businesses that implement structured documentation report improved team collaboration (Atlassian State of Teams report). The code block is a small feature, but it’s part of a larger system: teams that document clearly, communicate asynchronously, and reduce knowledge silos consistently outperform teams that don’t.

If your team’s Confluence pages are full of raw-pasted code that nobody wants to read — fixing that starts with the Code Block Macro. It takes seconds to implement and has a compounding effect on every engineer, product manager, or operations person who reads your docs.

Conclusion

Adding a code block in Confluence takes under 10 seconds once you know where to look. Type /code, configure your language and theme, and paste your snippet. That’s the core of it.

But the real value isn’t the feature itself — it’s what happens when your whole team uses it consistently. Clean, syntax-highlighted, titled code blocks mean less time searching for context, fewer “what does this do?” messages, and documentation that actually gets read.