Confluence Code Block Themes, Syntax Highlighting & Performance FAQ
Code blocks are one of the most frequently used macros in Confluence for engineering teams. Whether you are documenting API endpoints, sharing configuration files, or writing runbooks, the ability to embed readable, well-formatted code directly inside a Confluence page is essential. Yet the native code block macro that ships with Confluence has remained essentially unchanged for years: limited language support, no interactive editing, and a rendering approach that can bog down pages when multiple large snippets are present.
Teams that write technical documentation need proper syntax highlighting, fast page loads, and features like copy-to-clipboard and in-block search. This FAQ addresses the most common questions about code block performance in Confluence and explains how Modern Code Blocks for Confluence solves these problems by integrating the Monaco Editor — the same editor that powers VS Code — into your wiki pages.
Do large code blocks slow down Confluence pages?
Yes, they can. A single code block containing several hundred lines of code adds hundreds of DOM nodes to the page. When multiple large blocks appear on the same page, the browser must parse, style, and lay out all of those elements during the initial render. This increases time-to-interactive and can make scrolling feel sluggish, especially on older hardware or complex pages with embedded images and tables.
Modern Code Blocks for Confluence addresses this in two ways. First, it uses Monaco Editor with lazy initialization: the heavy editor component is not loaded until a user actually interacts with the code block. Until then, a lightweight static rendering handles the display. Second, the macro supports a configurable Max Height setting (100 to 5000 pixels) that enables vertical scrolling for long code. Code blocks automatically expand to fit their content up to the max height, keeping pages responsive.
If you regularly paste very large files into Confluence, consider linking to the source file in your repository instead and using the code block for the most relevant excerpt. This keeps the page responsive while still providing full context through the external link.
What is the performance impact of Monaco Editor in Confluence?
Monaco Editor is a full-featured code editor, and that richness comes with a larger JavaScript bundle compared to lightweight syntax highlighters like Prism or Highlight.js. Loading Monaco on every page view would add noticeable weight to the initial page load, particularly on pages with many macros.
Modern Code Blocks avoids this problem through client-side lazy loading. On a published page, the macro renders syntax-highlighted code as static HTML. The full Monaco Editor is only downloaded and initialized when a user clicks into a code block to edit it. This split approach means readers get fast, lightweight pages, while editors still have access to the full power of Monaco — including bracket matching, find and replace, and standard editor shortcuts — when they need it. Code blocks load on demand, not on page load, so the critical rendering path stays clear.
In practice, teams using Modern Code Blocks see no measurable difference in page load speed compared to the native Confluence code block, even though the editing experience is dramatically better.
How many programming languages does syntax highlighting support?
Modern Code Blocks for Confluence supports syntax highlighting for over 85 programming languages. This covers every mainstream language you would expect — JavaScript, TypeScript, Python, Java, C#, Go, Rust, Ruby, PHP, Swift, Kotlin, and C++ — plus a broad range of infrastructure and data languages such as SQL, YAML, JSON, TOML, HCL (Terraform), Dockerfile, Shell/Bash, PowerShell, and XML. Less common languages like Elixir, Haskell, R, Lua, and Julia are also included.
Language-specific grammar components are loaded on demand. When a page contains a Python code block and a YAML code block, only the tokenizers for those two languages are fetched. This on-demand loading strategy keeps each page lightweight regardless of how many total languages the plugin supports. You never pay the cost of loading grammars you are not using.
Can I search within code blocks in Confluence?
Yes. When you click into a code block to edit it, the Monaco Editor activates and provides built-in find and replace via the standard Ctrl+F (or Cmd+F on macOS) keyboard shortcut. The search bar supports regex matching, whole-word matching, and case-sensitive toggles, just like the find experience in VS Code. You can also open find-and-replace mode with Ctrl+H to quickly rename a variable across a snippet.
For published pages where the code is rendered as static HTML, Confluence's built-in browser page search (Ctrl+F outside the editor) can still find text inside code blocks. Modern Code Blocks generates semantic HTML that browsers can index, so in-page search works reliably across all major browsers without any extra configuration.
Are code blocks accessible for screen readers?
Accessibility is an important consideration for any team producing documentation that must meet WCAG guidelines or internal accessibility standards. Modern Code Blocks generates semantic HTML with proper ARIA labels so that screen readers can identify and navigate code content meaningfully. The code container is marked with the appropriate role and aria-label attributes, and line breaks are preserved in a way that assistive technology can interpret correctly.
The plugin also supports keyboard navigation within the Monaco Editor. Users can move through code line by line, jump to specific line numbers, and trigger common actions without touching a mouse. For teams that need to provide alternative formats, it is good practice to include a link to a downloadable plain-text version of the code alongside the embedded block.
Finally, both the dark and light themes included with Modern Code Blocks are designed with sufficient color contrast ratios for syntax highlighting. This ensures that color-coded tokens remain distinguishable for users with color vision deficiencies.
How do I export or copy code from Confluence code blocks?
Modern Code Blocks includes a copy button on every code block. With one click, the entire contents of the block are copied to the clipboard in plain text, ready to paste into a terminal, IDE, or configuration file. The copy button appears in the top-right corner of the block on hover, so it does not clutter the display but is always easy to reach.
For bulk export scenarios, you can use Confluence's built-in export to PDF feature, which preserves code formatting including syntax highlighting colors. If you need raw text for scripting or version control, you can also attach source files directly to the Confluence page and link to them from within the documentation. This dual approach — embedded code for readability, attached files for download — gives readers the best of both worlds.
Does Modern Code Blocks support dark and light themes?
Yes. Modern Code Blocks ships with both a dark theme and a light theme so that code blocks visually integrate with your Confluence space regardless of how it is styled. The dark theme uses a VS Code-inspired color palette that reduces eye strain during long reading sessions, while the light theme provides clean, high-contrast syntax highlighting for spaces that use a lighter color scheme.
Theme selection can be configured at the macro level, meaning you can use a dark theme for one code block and a light theme for another on the same page if needed. Both themes have been tested against WCAG 2.1 AA contrast requirements to ensure that syntax tokens remain readable for all users.
Comparison: Modern Code Blocks vs native Confluence code block vs Better Code Macro
| Feature | Modern Code Blocks for Confluence | Native Confluence Code Block | Better Code Macro |
|---|---|---|---|
| Editor engine | Monaco Editor (VS Code) | Plain text area | Prism.js highlighter |
| Initialization | Lazy — loads on demand | Immediate | Immediate |
| Languages supported | 85+ | ~30 | ~50 |
| Dark and light themes | Yes | Limited | Yes |
| Copy button | Built-in, on every block | No | Yes |
| Find and replace (Ctrl+F) | Yes | No | No |
| Keyboard navigation | Full Monaco keybindings | Basic | Basic |
| Max Height with scroll for long code | Yes | No | No |
| IntelliSense / autocomplete | No | No | No |
| On-demand grammar loading | Yes | No | No |
| Bracket matching | Yes | No | No |
| Line numbers toggle | Yes | Yes | Yes |
| Confluence Cloud support | Yes | Yes | Yes |
| Confluence Data Center support | No (Forge app) | Yes | Limited |
The table above summarizes how the three options compare. The native Confluence code block is fine for short, simple snippets where you just need basic monospace text with simple highlighting. Better Code Macro improves on that with Prism-based rendering and a copy button. Modern Code Blocks goes further by embedding a full Monaco Editor experience with lazy loading, 85+ languages, find-and-replace, configurable Max Height, and themes — all while keeping page performance comparable to the lightweight alternatives.
Best practices for code blocks in Confluence
1. Keep snippets short and focused
Resist the temptation to paste an entire 2,000-line file into a single code block. Instead, extract the 20 to 50 lines that are actually relevant to the point you are making. If readers need the full file, link to it in your source repository or attach it as a downloadable file. Shorter blocks render faster, are easier to scan visually, and make your documentation more readable overall.
2. Always specify the language
Explicitly setting the language on every code block ensures correct syntax highlighting. When the language is set to "auto" or left blank, the highlighter must guess, and it frequently guesses wrong — especially for short snippets where several languages share similar syntax. Taking two seconds to select "Python" or "YAML" from the dropdown saves every future reader from staring at un-highlighted or incorrectly highlighted code.
3. Use Max Height for long reference material
Configuration files, JSON payloads, and log excerpts are often necessary for completeness but are rarely the primary focus of a page. Set a reasonable Max Height for these code blocks so that the page stays scannable and the narrative flow is not interrupted by walls of text. Readers can scroll within the block to see the full content without navigating away from the page.
4. Add a title or filename to each block
A code block without context forces the reader to guess which file the code comes from or where it should be placed. Add context above the code block — such as a filename like docker-compose.yml or a description like main.py — API handler — so that readers immediately understand what they are looking at.
5. Leverage the copy button for runnable code
When documenting installation steps, CLI commands, or quick-start scripts, structure the code so that it can be copied and run directly. Avoid splitting a single command across multiple code blocks, and make sure environment variables or placeholders are clearly marked. The built-in copy button in Modern Code Blocks means a reader can go from reading your documentation to running the code in a single click, which dramatically reduces friction in onboarding and incident-response workflows.
Related resources
- Modern Code Blocks for Confluence — documentation
- Advanced code blocks in Confluence — full how-to guide
- Enhanced Markdown for Confluence — Markdown editing with code support
- Confluence Markdown vs WYSIWYG FAQ