How to Edit the Confluence Storage Format (And When You'd Need To)
- Confluence admins fixing broken pages, macros, or corrupted formatting
- Developers migrating or bulk-editing page content via the storage format
- Power users who need find-and-replace across a page's underlying XML
- What the Confluence storage format is and why you'd edit it directly
- How to open the raw XML of a page and make safe changes
- Formatting, find-and-replace, and diffing changes before saving
- When editing storage format is the right tool (and when it isn't)
Most Confluence users never see it, but every page is stored as an XML document in Confluence's storage format — a specific XHTML dialect with custom tags for macros, layouts, and embeddings. The visual editor hides this. But sometimes the only way to fix a problem is to edit that XML directly: a macro is corrupted and won't render, a copy-paste introduced broken formatting, or you need to find-and-replace a URL across a long page that the visual editor can't reach.
Confluence exposes the storage format through its REST API, but there's no built-in visual editor for it. Raw Storage Source Editor for Confluence adds one — a Monaco-powered editor that opens the raw storage XML of any page, with format, find-and-replace, and (in the Pro edition) a diff view. This guide covers when and how to use it safely.
What is the Confluence storage format?
The storage format is the canonical representation of a Confluence page — the XML that Confluence itself stores and renders. It looks like this:
<h1>Project Overview</h1>
<p>This document covers the Q3 release plan.</p>
<ac:structured-macro ac:name="info">
<ac:rich-text-body>
<p>Reviewers: please comment by Friday.</p>
</ac:rich-text-body>
</ac:structured-macro>
Standard HTML tags (<h1>, <p>, <table>) sit alongside Confluence-specific namespaced tags (<ac:structured-macro>, <ac:layout>, <ri:attachment>). Macros, layouts, embedded images, and links all have dedicated storage-format tags. When you edit in the visual editor, Confluence updates this XML behind the scenes. When you edit the XML directly, you're changing exactly what Confluence stores.
When you'd edit the storage format directly
Editing storage format is a power-user tool. It's the right approach when:
| Problem | Why storage-format editing helps |
|---|---|
| A macro is corrupted and won't render | The macro's XML is malformed; fix the tag structure directly |
| Broken formatting from a bad copy-paste | Pasted content left stray tags; clean them out of the XML |
| Find-and-replace across a long page | The visual editor's find is limited; the XML editor has full find/replace |
| Bulk-editing repeated structures | e.g. updating the same macro parameter in 20 places on one page |
| Removing an embedded resource that's stuck | A broken <ri:attachment> reference that the UI won't let you delete |
| Migrating content between formats | Inspecting and adjusting the XML during a migration |
It is not the right tool for everyday editing — the visual editor is faster and safer for normal content changes. Use the source editor when the visual editor can't reach or fix the problem.
Step-by-step: edit a page's storage format
1. Install Raw Storage Source Editor for Confluence
Install Raw Storage Source Editor for Confluence (Free edition) or Source Editor Pro from the Marketplace. Both are free for up to 10 users. After installation, a Source Editor option appears in the More Actions menu on every page.
2. Open the source editor
Open the Confluence page you want to edit. Click the More Actions (⋯) button and choose Source Editor for Confluence. The editor opens, showing the page's raw storage format XML.
3. Edit, format, or find-and-replace
The editor is Monaco-based (the same engine as VS Code), so the shortcuts are familiar:
- Format Document — right-click and choose Format Document to clean up messy or inconsistently indented XML. This makes the structure readable before you edit.
- Find / Find and Replace —
Ctrl+F(find) andCtrl+H(find and replace). Useful for updating a repeated value (a URL, a parameter) across the page. - Command palette — press
F1orCtrl+P/Cmd+Pto see all available editor functions.
Make your changes carefully. Storage-format XML is strict — an unclosed tag or a broken ac: namespace reference can prevent the page from rendering. If you're unsure, test on a copy of the page first.
4. Preview the diff (Pro edition) and save
In the Pro edition, a Diff View button appears once you've made changes. Click it to open a side-by-side comparison: the original on the left, your changes on the right. This is the safest way to verify exactly what you changed before committing it.
Review the diff. Once you're confident, save to apply the changes to the page. The page re-renders with your storage-format edits applied.
Free vs. Pro: which do you need?
| Feature | Free | Pro |
|---|---|---|
| Edit raw storage format XML | ✅ | ✅ |
| Format Document | ✅ | ✅ |
| Find and find-and-replace | ✅ | ✅ |
| Command palette | ✅ | ✅ |
| Diff View (compare changes before saving) | — | ✅ |
| Theme switching (Light / Dark / High Contrast) | — | ✅ |
For occasional fixes, the Free edition is enough. For regular bulk-editing or migration work, the Pro edition's diff view is worth it — it catches mistakes before they hit the page.
A warning: storage format is powerful but unforgiving
Editing storage format is the most direct way to change a Confluence page, which means it's also the easiest way to break one. Three rules:
- Test on a copy first if you're doing anything beyond a simple find-and-replace. Copy the page, edit the copy's storage format, verify it renders, then apply the same change to the real page.
- Respect the
ac:andri:namespaces. These are Confluence's custom tags. Don't rename or remove namespace declarations; a broken namespace reference can corrupt the page. - Use the diff view (Pro) before saving. It's much easier to spot a stray deleted closing tag in a diff than in the rendered result.
FAQ
Can you edit the source code of a Confluence page?
Yes, but "source code" means the page's storage format XML, not HTML. Confluence stores every page as XML in a custom XHTML dialect with namespaced tags for macros and layouts. The Raw Storage Source Editor app lets you open and edit this XML directly from the More Actions menu.
How do I access the Confluence storage format?
Confluence exposes the storage format through its REST API (/rest/api/content/{id}?expand=body.storage), but there's no built-in visual editor for it. To edit it interactively, install a Marketplace app like Raw Storage Source Editor for Confluence, which adds a source-editor option to the page's More Actions menu.
Is editing Confluence storage format safe?
It's safe if you're careful and test on a copy first. The storage format is strict XML — an unclosed tag or a broken macro namespace reference can prevent the page from rendering. For anything beyond a simple find-and-replace, use the diff view (Pro edition) to verify your changes before saving.
What is the difference between Source Editor Free and Pro?
Both editions let you edit the raw storage format XML with format, find, and find-and-replace. The Pro edition adds a diff view (side-by-side comparison of your changes against the original) and theme switching. The diff view is the key Pro feature for anyone doing regular or complex edits.
Is Raw Storage Source Editor for Confluence free?
The Free edition is free for up to 10 users. The Pro edition (with diff view and themes) is also free for up to 10 users; beyond that, standard Marketplace licensing applies.
Related guides
Try Raw Storage Source Editor for Confluence
Edit the raw XML storage format of Confluence pages with format, find-and-replace, and diff view — free for up to 10 users.
Get it on the Atlassian Marketplace →