Show code, JSON, and API docs in Confluence

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. 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. 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. 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. 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. 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. 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

Read the guides

• → Display Json Xml Code In Confluence
• → Confluence Code Editor Syntax Highlighting
• → Advanced Code Blocks Confluence
• → Faq Code Blocks Performance
• → Embed Json Confluence
• → Confluence Json Schema Viewer