How to Display JSON, XML, YAML & Code in Confluence (With Syntax Highlighting)
- Developer teams documenting APIs, configs, and schemas in Confluence
- Tech writers who need formatted code samples alongside prose
- Anyone pasting JSON, XML, YAML, or SQL into Confluence and getting an unreadable wall of text
- Why Confluence's built-in code block struggles with JSON, XML, and config files
- How to embed syntax-highlighted code in 85+ languages using a Monaco-powered editor
- Theme configuration, diff views, and screenshot-ready window chrome
- When to use a code block vs. a visual JSON structure diagram
The scenario every engineering team hits: you're documenting an API in Confluence, and the page needs to show a JSON response, an XML config, a YAML deployment manifest, and a SQL query — all on the same page. You paste each one into Confluence's built-in code block macro, publish, and the result is a wall of monochrome text. No syntax colors. No line numbers that work. JSON braces, XML tags, and YAML indentation all blur together. The reader has to copy-paste your snippet into VS Code just to understand it.
The root problem is that Confluence's native code block uses a basic highlighter that wasn't built for the structured data formats modern teams actually work with. JSON, XML, YAML, and SQL each have specific visual conventions — matched braces, nested tags, indentation scopes — that a generic highlighter doesn't handle well.
Modern Code Blocks for Confluence solves this by bringing the Monaco Editor — the same engine that powers VS Code — into Confluence. It accurately highlights 85+ languages including JSON, XML, YAML, SQL, GraphQL, Terraform, Dockerfile, and every mainstream programming language. This guide walks through embedding formatted code and data formats in your Confluence pages.
Why the native Confluence code block falls short for JSON and XML
Confluence ships with a built-in Code Block macro. It works for short snippets, but teams documenting real systems run into three recurring problems:
1. Limited and inaccurate syntax highlighting. The native macro uses a basic regex highlighter. For JSON, nested objects and arrays often lose their color context as depth increases. For XML, attribute values and tag names aren't consistently distinguished. YAML's indentation-based scoping — where a single misaligned space breaks the file — gets no visual emphasis at all.
2. No live preview while editing. You write code into a plain text area and only see how it renders after you save and publish. If the highlighting is wrong or a line wraps awkwardly, you're back into edit mode to fix it. This round-trip adds up when you're building an API doc page with 10+ code samples.
3. No theme control. The native block has a single visual style. If your Confluence is in dark mode, the code block doesn't match — it stays light. There's no way to pick a theme that fits your page or your team's preference.
The Monaco Editor difference
Monaco is the editor technology behind VS Code. It understands language grammar at a deep level — not just keywords, but token types, bracket matching, and scope-aware coloring. When you bring it into Confluence via Modern Code Blocks, JSON, XML, and YAML get the same quality of highlighting you'd see in your IDE.
| Format | Native Confluence code block | Modern Code Blocks (Monaco) |
|---|---|---|
| JSON | Flat highlighting; nested objects lose color depth | Key, string, number, boolean tokens each get distinct colors; bracket matching |
| XML | Tags and attributes often the same color | Tag names, attributes, values, and comments all differentiated |
| YAML | Treated as plain text in most cases | Keys, values, anchors, and comments highlighted; indentation visually clear |
| SQL | Basic keyword highlighting | Dialect-aware (MySQL, PostgreSQL); keywords, functions, strings separated |
| Theme | One fixed style | Auto light/dark + 50+ premium themes (Monokai, Dracula, GitHub Dark, …) |
| Editing | Plain text area, no preview | Monaco editor with live preview before you save |
Step-by-step: display formatted JSON, XML, or YAML in Confluence
1. Install Modern Code Blocks for Confluence
Go to the Modern Code Blocks listing on the Atlassian Marketplace and click Get it now. The app installs into your Confluence Cloud instance. It's free for up to 10 users.
Once installed, the macro appears in Confluence's macro browser under the name Modern Code Blocks for Confluence.
2. Insert the code block macro
Edit any Confluence page. In the editor, type /modern code or /code and select Modern Code Blocks for Confluence from the dropdown. The configuration panel opens with the Monaco editor on the left and settings on the right.
3. Paste your content and pick a language
Paste your JSON, XML, YAML, SQL, or any code into the Monaco editor. Then select the language from the Language dropdown. The editor immediately applies accurate syntax highlighting.
Here's what each major format looks like:
JSON — select "JSON" from the language dropdown. Keys, string values, numbers, booleans, and null each get distinct colors. Nested objects and arrays are bracket-matched, so readers can trace structure at a glance. This is the format teams search for most: "how to show JSON in Confluence".
XML — select "XML". Tag names, attribute names, attribute values, comments, and CDATA sections are all visually differentiated. This matters for teams documenting SOAP APIs, Maven POMs, or Confluence's own storage format.
YAML — select "YAML". Keys, values, comments, and anchors are highlighted. Because YAML's structure depends entirely on indentation, the visual emphasis on scope helps readers spot misalignment that would break parsing.
SQL — select your dialect (MySQL, PostgreSQL, or generic SQL). Keywords, function names, string literals, and numeric values are separated.
The full supported list covers 85+ languages, including Python, TypeScript, Go, Rust, Java, C#, GraphQL, Terraform, Dockerfile, Shell/Bash, and more.
4. Configure the theme and display
Before saving, configure how the block looks to readers:
- Theme — Auto matches each reader's Confluence light/dark setting automatically. Or pick a fixed theme: 4 built-ins (VS Code Light, VS Code Dark, High Contrast) or 50+ premium themes in the Advanced edition (Monokai, Dracula, Nord, Solarized, GitHub Dark, One Dark Pro, and more).
- Line Numbers — On, Off, or Relative (relative numbering is useful for Vim users reading vimdiff-style output).
- Font Size — 8–32px. The default 14px works for most documentation; bump to 16px for presentation pages.
- Max Height — the block auto-sizes to fit content, up to this limit (100–5000px). Code beyond the limit scrolls. This prevents a 500-line JSON file from consuming the entire page.
- Word Wrap — wrap long lines or allow horizontal scroll. For JSON with long single-line values, wrapping is usually kinder to readers.
- Show Minimap — a VS Code-style code overview in the corner. Useful for very long code samples where readers need to jump around.
5. Save and publish
Click Save to insert the rendered code block. Publish the page. Every viewer sees the code with your chosen language highlighting and theme — the rendering is consistent across readers, browsers, and Confluence themes.
Advanced: diff views for migration guides and changelogs
When you're documenting a code change — a config migration, an API version bump, a refactor — a before/after comparison is clearer than two separate blocks. Modern Code Blocks (Advanced edition) supports a Diff View:
- Set View Mode to Diff
- Paste a unified diff (
.patch/.diffformat) or upload a.patchfile - Pick a Render Mode:
- Raw — the patch text with
+lines in green,-lines in red (GitHub-style) - Inline — the diff parsed and interleaved into a single view (the layout
git diffproduces)
- Raw — the patch text with
- Optionally choose a separate theme for the diff block
This is ideal for release notes, migration guides, and changelogs where the reader needs to see exactly what changed.
Advanced: window chrome for screenshot-ready snippets
If you're publishing code samples to marketing pages, landing pages, or external-facing documentation, plain code blocks can look flat. The Advanced edition's Window Chrome option wraps your block in an OS-style title bar:
- macOS — three traffic-light buttons on the left
- Windows — three caption buttons on the right
The title bar auto-derives a filename from your selected language (main.js for JavaScript, config.yaml for YAML, response.json for JSON). The result looks like a screenshot from a real editor — the aesthetic popularized by carbon.now.sh and ray.so, but inline in your Confluence page.
When to use a code block vs. a visual JSON diagram
Modern Code Blocks and JSON Structure Viewer for Confluence serve different purposes. Here's how to choose:
| You want to… | Use |
|---|---|
| Show formatted, syntax-highlighted JSON/XML/YAML/code that developers can read like an IDE | Modern Code Blocks |
| Visualize the structure of a JSON object as a collapsible tree or diagram for non-developers | JSON Structure Viewer |
| Show a JSON API response in a developer guide | Modern Code Blocks (developers want syntax colors) |
| Show a complex nested JSON schema to a business analyst | JSON Structure Viewer (they want the tree view) |
Many teams use both on the same page: a code block for the raw JSON, and a structure diagram below it for the visual breakdown.
FAQ
Does Confluence have a native way to display JSON?
Confluence's built-in Code Block macro supports JSON as a language, but its highlighting is basic — nested structures lose color depth, and there's no live preview. For JSON-heavy documentation (APIs, configs), a Monaco-powered editor like Modern Code Blocks produces significantly more readable output.
Can I display XML and YAML in Confluence too?
Yes. Modern Code Blocks supports XML, YAML, JSON, and 85+ other languages with accurate Monaco-based highlighting. Each format gets language-aware token coloring — XML tag names vs. attributes, YAML keys vs. values, etc.
How do I show code in Confluence dark mode?
Modern Code Blocks has an Auto theme that matches each reader's Confluence light/dark setting automatically. When Confluence is in dark mode, the code block renders in VS Code Dark; in light mode, it uses VS Code Light. You can also force a specific theme per block.
Can I copy code from a Confluence page?
Yes. Every Modern Code Blocks snippet includes a copy button in the top-right corner for one-click copying. This is especially useful for JSON configs and SQL queries that readers need to paste elsewhere.
How many languages does Modern Code Blocks support?
85+ languages, including JSON, XML, YAML, SQL (MySQL, PostgreSQL), Python, TypeScript, JavaScript, Go, Rust, Java, C#, GraphQL, Terraform, Dockerfile, Shell/Bash, HTML, CSS/SCSS, PHP, Ruby, Scala, Kotlin, Swift, and many more.
Is Modern Code Blocks free?
Modern Code Blocks is free for up to 10 users. The Advanced edition (50+ premium themes, diff view, window chrome) is unlocked by the license tier purchased on the Atlassian Marketplace. Trial licenses unlock all Advanced features for the duration of the trial.