# Show code, JSON, and API docs in Confluence

Confluence’s basic code macro is not enough for technical content. Learn how to present code, JSON, and OpenAPI specs so readers actually get it.

> Present code, JSON, and API documentation in Confluence with syntax highlighting and interactive viewers — readable technical content for the whole team.

## Why this matters in Confluence

Confluence is where engineering teams share code snippets, API contracts, payload examples, and runbooks. The built-in code macro is plain and error-prone, raw JSON pasted into a page is unreadable at any real scale, and an OpenAPI spec dropped in as text is a wall of YAML that nobody navigates. The result is that technical content either gets under-documented or pushed out to a separate tool, fragmenting the knowledge base so that the wiki and the code drift apart within weeks.

### Code deserves real syntax highlighting

A wall of uncoloured code hides typos, missed brackets, and wrong keywords, and it slows every reader who has to parse it. Proper highlighting, a choice of themes, line numbers, and a one-click copy button turn a snippet into something the team can actually paste into a terminal or review the way they would in their editor. The difference is not cosmetic — it is the difference between a snippet that gets used and one that gets ignored.

### JSON is structure, not prose

Nested JSON inside a code block forces readers to scroll and count braces to find the field they care about. A collapsible tree view turns a payload into something a reader can expand, collapse, and search in seconds — drilling into the one nested object that matters without losing their place. For request and response examples, this is what makes the difference between a payload that explains itself and one that intimidates.

### API docs are content, not a separate site

OpenAPI and Swagger specs describe exactly how systems talk, but most teams host them on a standalone portal that drifts from the wiki. Embedding the spec as interactive documentation — expandable endpoints, parameters, schemas, and examples — keeps the internal API docs next to the code that consumes them, so a change to either is visible in the same place at the same time.

### Language coverage has to be real

The built-in code macro supports a limited set of languages and lags far behind what engineers actually write — Terraform, modern TypeScript, Rust, and newer config formats are often missing or mis-highlighted. A code block built on a real editor engine like Monaco (the same one VS Code uses) covers 80+ languages and keeps up with new ones, so a snippet always renders correctly instead of falling back to plain text.

### Specs go stale when they are screenshots

A pasted image of an API endpoint or a copied YAML blob goes stale the moment the service ships a new version. A spec rendered live from its source — or re-pasted and re-rendered on each release — stays honest, and the reader can trust that what they are reading reflects the current state of the system rather than a snapshot from last quarter.

## The approach that works

The pattern for technical content in Confluence is to render it natively rather than paste it as text or images: use a real syntax-highlighting code block, visualise structured data with a tree viewer, and embed API specs as live, navigable documentation. Each step below covers a content type, when to use it, and how to keep it from drifting away from the source it describes.

1. **Use a real code block, not the built-in macro.** Replace the built-in code macro with a syntax-highlighting code block that supports your languages, offers light and dark themes, follows the reader's colour scheme, and has a copy button. Use it for every snippet longer than a couple of lines — shell commands, configuration, SQL, Terraform, and inline examples in runbooks — because the copy button alone saves readers a select-and-copy dance on every block.

2. **Visualise JSON and nested data as a tree.** For nested JSON, XML, or YAML, paste the payload into a structure viewer so readers can expand and collapse nodes instead of scanning formatted text. Use this whenever the structure is more than two levels deep or whenever a reader will need to find one specific field — request and response bodies, config dumps, and webhook payloads all qualify.

3. **Embed OpenAPI and Swagger specs interactively.** Paste your OpenAPI or Swagger spec into an interactive viewer so endpoints, parameters, request bodies, response schemas, and examples render as navigable docs. Use this for any internal API page that engineers will reference repeatedly; it turns a static spec file into a documentation surface that supports lookups, not just reading.

4. **Pick the right view for the audience.** Engineers often want the raw source so they can copy it; product and support readers want the rendered, expanded view so they can understand it. Good tooling offers both — a collapsible tree with a toggle back to raw text, or a rendered API page with a link to the underlying YAML — so one piece of content serves both audiences without maintaining two copies.

5. **Link the page to its source of truth.** Keep the snippet, payload, or spec versioned somewhere it can be regenerated — a repo, a CI artifact, or an API gateway export — and link the Confluence page to it so docs never silently diverge. The page is for explanation and context; the source is for authority. When they disagree, the link tells the reader which one wins.

6. **Refresh on a cadence, not on memory.** Specs and example payloads rot if nobody owns them. Tie the refresh to the release cycle — re-paste the spec when a new version ships, or re-export the example payload after a schema migration — and note the version or date inline so a reader can tell at a glance whether the page is current. A small dating convention is what separates living docs from an archive of the past.

## This solution is for you if…

- Engineering teams sharing code snippets, configs, and request payloads

- API and platform teams documenting endpoints, schemas, and integration contracts

- QA and DevOps teams writing runbooks, postmortems, and incident guides

- Developer relations and partner teams publishing internal API documentation

- Backend and data teams documenting event payloads, schemas, and migration scripts

## Our apps that solve this

- **[Modern Code Blocks for Confluence](/apps/modern-code-blocks-for-confluence.md)** — Syntax-highlighted code blocks with 85+ languages, auto theme sync, and a live preview editor for Confluence pages · [Install from Atlassian Marketplace](https://marketplace.atlassian.com/apps/3525717923/modern-code-blocks-for-confluence?utm_source=ngpilot.com&utm_medium=website&utm_campaign=scenario-code-and-api-docs-in-confluence)

- **[Modern OpenAPI (Swagger) Integration for Confluence](/apps/modern-openapi-swagger-integration-for-confluence.md)** — Render OpenAPI and Swagger specifications directly on Confluence pages with an interactive, theme-aware viewer · [Install from Atlassian Marketplace](https://marketplace.atlassian.com/apps/2844069010/modern-openapi-swagger-integration-for-confluence?utm_source=ngpilot.com&utm_medium=website&utm_campaign=scenario-code-and-api-docs-in-confluence)

## Read the guides

- [Display JSON, XML & Code in Confluence](/blog/display-json-xml-code-in-confluence.md)

- [Dark Mode for Confluence Code Blocks — Setup Walkthrough](/blog/confluence-code-editor-syntax-highlighting.md)

- [Advanced Code Blocks: Performance Tuning & Tips](/blog/advanced-code-blocks-confluence.md)

- [Modern Code Blocks Performance & Large Snippet FAQ](/blog/faq-code-blocks-performance.md)

- [Display JSON in Confluence (Blocks + Viewer)](/blog/embed-json-confluence.md)

- [JSON Viewer for Confluence: Blocks vs Structure](/blog/confluence-json-schema-viewer.md)

## Frequently asked questions

### How do I show JSON or XML nicely in Confluence?

Confluence's built-in code macro is basic and does not handle deeply nested data well. Use a code-block app powered by the Monaco editor (the same engine as VS Code) to render JSON, XML, YAML, SQL, and 80+ more languages with proper highlighting, themes, line numbers, and a copy button. For deeply nested payloads, a structure viewer turns the same JSON into a collapsible tree that readers can navigate instead of scroll.

### Can I render an OpenAPI spec on a Confluence page?

Yes. An OpenAPI integration renders your spec as interactive documentation with expandable endpoints, parameters, request and response schemas, validation, and syntax highlighting. It is ideal for internal API docs because the rendered page lives next to the wiki content that surrounds it, instead of on a separate portal that drifts out of sync.

### How do I make a Confluence code block copyable with syntax highlighting?

The native code macro has no copy button and limited highlighting. A modern code-block app adds a one-click copy button, full Monaco-based syntax highlighting across 80+ languages, light and dark themes, and automatic theme switching to match the reader's preference. The result reads like a snippet from your editor rather than a plain-text dump.

### What is the best way to display a large JSON payload in Confluence?

For anything beyond a few fields, paste the JSON into a structure viewer that renders it as a collapsible tree. Readers expand only the nodes they care about, search for specific keys, and copy individual values, instead of scrolling through hundreds of lines of formatted text. Keep a link to the raw source alongside it so engineers can grab the full payload when they need it.

### Does the built-in Confluence code macro support my programming language?

Only partially. The built-in macro supports a limited set of languages and lags behind newer ones like modern TypeScript, Rust, Terraform, and recent config formats. A code-block app built on Monaco inherits VS Code's language grammar coverage, so snippets render correctly without falling back to plain text, and new languages are added as the editor engine evolves.

### How do I keep Confluence API docs in sync with the actual API?

Treat the spec as the source of truth and the Confluence page as the explanation layer. Re-paste or re-link the OpenAPI spec whenever a new version ships, note the version or date inline so readers know how current the page is, and link out to the repo or API gateway where the canonical spec lives. A short cadence tied to releases is what keeps docs honest.

## Ready to try it?

All NGPILOT apps are free for up to 10 users and install in one click from the Atlassian Marketplace. Browse the [full app catalog](/apps.md) or read more [scenario solutions](/solutions.md).