Confluence Storage Format

When upgrading from Confluence 3.x to Confluence 4.x, the underling storage format for your content will be migrated from a wiki markup-based format to a new XHTML-based format. This page highlights the differences between these two type of markup.

As of Confluence 4.0, you can view the Confluence storage format for a given page by selecting the "View Storage Format" option available in the Tools menu. This option is not visible by default - It is only visible to you if:
- You are a Confluence administrator or
- Your administrator has installed the Confluence Source Editor plugin and enabled it for you.
Editing Confluence source will require the Confluence Source Editor plugin - please see the specification for details.

Still considering

Provide an XSD - "an XSD could make on the fly validation for persons having an editor supporting it (E.g. Visual Studio), and since an XSD would be a way to validate your input. CONF-24884 - Getting issue details... STATUS

Intended Audience

This page is intented for developers and advanced users who need to interpret and edit the underlying markup for a Confluence page or blog post.

Content Categories

Macros

Below are some examples of the source markup for common Confluence macros. Rather than document the source for every macro included in Confluence, the goal of this page is to give you guidelines and examples of how the macros are defined within the Confluence storage format.

Info Macro

The info macro is a good example of a macro that accepts a rich text body. Below are three examples of the info macro with various optional parameters used.

Format Type	In Confluence 3.5 and below	In Confluence 4.0 and above	What you will get
Info macro with a body defined and no optional parameters	{info}this is _important_ information{info}	<ac:macro ac:name="info"> <ac:rich-text-body><p>this is <em>important</em> information</p></ac:rich-text-body></ac:macro>	This is my title this is important information
Info macro with with a body and an optional Title parameter defined	{info:title=This is my title} this is _important_ information {info}	<ac:macro ac:name="info"> <ac:parameter ac:name="title">This is my title</ac:parameter> <ac:rich-text-body><p>this is <em>important</em> information</p></ac:rich-text-body> </ac:macro>	This is my title this is important information
Info macro with a body and optional Title and Icon parameters defined	{info:title=This is my title\|icon=false} this is _important_ information {info}	<ac:macro ac:name="info"> <ac:parameter ac:name="icon">false</ac:parameter> <ac:parameter ac:name="title">This is my title</ac:parameter> <ac:rich-text-body><p>this is <em>important</em> information</p></ac:rich-text-body> </ac:macro>	This is my title this is important information
Expand macro with default macro parameter	{expand:test title} this is _important_ information {expand}	<ac:macro ac:name="expand"> <ac:default-parameter>test title</ac:default-parameter> </ac:macro>	test title this is important information

Code Block Macro

The code block macro is a good example of a macro that accepts a plain text body. Below are three examples of the code macro with various optional parameters used.

Format Type

In Confluence 3.5 and below

In Confluence 4.0 and above

What you will get

Code block macro with a body and no option parameters

{code}this is my code{code}

<ac:macro ac:name="code">
	<ac:plain-text-body><![CDATA[this is my code]]></ac:plain-text-body>
</ac:macro>

this is my code

Code block macro with a body optional language parameter defined

{code:language=html/xml}this is my code{code}

<ac:macro ac:name="code">
	<ac:parameter ac:name="language">html/xml</ac:parameter>
	<ac:plain-text-body><![CDATA[this is my code]]></ac:plain-text-body>
</ac:macro>

this is my code

Code block macro with a body and optional title, line numbers and language parameters defined

{code:language=html/xml|title=This is my title|linenumbers=true}this is my code{code}

<ac:macro ac:name="code">
	<ac:parameter ac:name="title">This is my title</ac:parameter>
	<ac:parameter ac:name="linenumbers">true</ac:parameter>
	<ac:parameter ac:name="language">html/xml</ac:parameter>
	<ac:plain-text-body><![CDATA[this is my code]]></ac:plain-text-body></ac:macro>

This is my title

this is my code

The body of a plain text macro must be inside a CDATA block. So the following is not sufficient:

<ac:plain-text-body>text</ac:plain-text-body>

The correct usage is:

<ac:plain-text-body><![CDATA[text]]></ac:plain-text-body>

Table of Contents Macro

The table of contents macro is a good example of a macro that does not accept a body. Below are two examples:

Format Type

In Confluence 3.5 and below

In Confluence 4.0 and above

What you will get

Table of contents macro with no parameters

{toc}

<ac:macro ac:name="toc" />

Table of contents with optional minLevel and type parameters defined

{toc:type=flat|minLevel=3}

<ac:macro ac:name="toc">
	<ac:parameter ac:name="minLevel">3</ac:parameter>
	<ac:parameter ac:name="type">flat</ac:parameter>
</ac:macro>

Headings

Format Type	In Confluence 3.5 and below	In Confluence 4.0 and above
Heading 1	`h1. Heading 1`	<h1>Heading 1</h1>	Underlined in the Documentation Theme
Heading 2	h2. Heading 2	<h2>Heading 2</h2>	Underlined in the Documentation Theme
Heading 3	h3. Heading 3	<h3>Heading 3</h3>
Heading 6	h6. Heading 6	<h6>Heading 6</h6>

Text Effects

Format Type	In Confluence 3.5 and below	In Confluence 4.0 and above	What you will get
strong/bold	strong	<strong>strong text</strong>	strong	<b> will also work but get converted to <strong> upon saving
emphasis	_emphasis_	<em>Italics Text</em>	emphasis	<i> will also work but get converted to <em> upon saving
strikethrough	-strikethrough-	<span style="text-decoration: line-through;">strikethrough</span>	~~strikethrough~~	<s> and <del> will also work
underline	+underline+	<u>underline</u>	underline
superscript	^superscript^	<sup>superscript</sup>	^superscript
subscript	~subscript~	<sub>subscript</sub>	_subscript
monospace	{{monospaced}}	<code>monospaced</code>	`monospaced`
preformatted	n/a	<pre>preformatted text</pre>	preformatted text
block quotes	bq. block quote or {quote} block quote {quote}	<blockquote><p>block quote</p></blockquote>	block quote
text colour	{color:red}red text{color}	<span style="color: rgb(255,0,0);">red text</span>	red text
small	n/a	<small>small text</small>	small text
big	n/a	<big>big text</big>	big text

Text Breaks

Format Type	In Confluence 3.5 and below	In Confluence 4.0 and above	What you will get
New paragraph	Paragraph 1 (empty line) Paragraph 2	<p>Paragraph 1</p> <p>Paragraph 2</p>	Paragraph 1 Paragraph 2
Line break	Line 1 \\ Line 2	Line 1 <br /> Line 2 Note: Created in the editor using `Shift + Return/Enter`	Line 1 Line 2
Horizontal Rule	----	<hr />
— symbol	---	—	—
– symbol	--	–	–

Lists

Format Type

In Confluence 3.5 and below

In Confluence 4.0 and above

What you will get

Unordered List - Round Bullets

* Round bullet list item

<ul>
  <li>round bullet list item</li>
</ul>

Round bullet list item

Unordered List - Square Bullets

- Square bullet list item

<div>
  <ul style="list-style-type: square;">
    <li>square bullet list item</li>
  </ul>
</div>

Square bullet list item

Ordered List

# Ordered list item

<ol>
  <li>numbered list item</li>
</ol>

Ordered list item

Links

Format Type	In Confluence 3.5 and below	In Confluence 4.0 and above	What you will get
Link to another Confluence page	[Link to another Confluence page\|Page Title]	<ac:link> <ri:page ri:content-title="Page Title" /> <ac:plain-text-link-body> <![CDATA[Link to another Confluence Page]]> </ac:plain-text-link-body> </ac:link>	Link to another Confluence page
Link to an attachment	[Link to an attachment^atlassian_logo.gif]	<ac:link> <ri:attachment ri:filename="atlassian_logo.gif" /> <ac:plain-text-link-body> <![CDATA[Link to a Confluence Attachment]]> </ac:plain-text-link-body> </ac:link>	Link to an attachment
Link to an external site	[Atlassian\|http://www.atlassian.com/]	<a href="http://www.atlassian.com">Atlassian</a>	Atlassian
Anchor link	[Anchor Link\|pagetitle#anchor]	<ac:link ac:anchor="Anchor Link"> <ac:plain-text-link-body> <![CDATA[Anchor Link]]> </ac:plain-text-link-body> </ac:link>	Anchor Link
Link with an embedded image for the body	[!google.png!\|pagetitle#anchor]	<ac:link ac:anchor="Anchor Link"> <ac:link-body> <ac:image><ri:url ri:value="http://confluence.atlassian.com/images/logo/confluence_48_trans.png" /></ac:image> </ac:link-body> </ac:link> For rich content like images, you need to use `ac:link-body` to wrap the contents.

A Note on Link Bodies

All links received from the editor will be stored as plain text by default, unless they are detected to contain the limited set of mark up that we allow in link bodies. Here are some examples of markup we support in link bodies.

An example of different link bodies

<ac:link>
    <!-- Any resource identifier --> 
    <ri:page ri:content-title="Home" ri:space-key="SANDBOX" /> 
    <ac:link-body>Some <strong>Rich</strong> Text</ac:link-body>
</ac:link>

<ac:link>
    <ri:page ri:content-title="Plugin developer tutorial stuff" ri:space-key="TECHWRITING" />
    <ac:plain-text-link-body><![CDATA[A plain <text> link body]]></ac:plain-text-link-body>
</ac:link>

<ac:link>
    <ri:page ri:content-title="Plugin developer tutorial stuff" ri:space-key="TECHWRITING" />
    <!-- A link body isn't necessary. Auto-generated from the resource identifier for display. --> 
</ac:link>

Images

Format Type

In Confluence 3.5 and below

In Confluence 4.0 and above

What you will get

Attached Image

!atlassian_logo.gif!

<ac:image>
  <ri:attachment ri:filename="atlassian_logo.gif" />
</ac:image>

External Image

!http://confluence.atlassian.com/images/logo/confluence_48_trans.png!

<ac:image>
  <ri:url ri:value="http://confluence.atlassian.com/images/logo/confluence_48_trans.png" /></ac:image>

Table of supported image attributes (some of these attributes mirror the equivalent HTML 4 IMG element):

Name	Description
ac:align	image alignment
ac:border	Set to "true" to set a border
ac:class	css class attribute.
ac:title	image tool tip.
ac:style	css style
ac:thumbnail	Set to "true" to designate this image as a thumbnail.
ac:alt	alt text
ac:height	image height
ac:width	image width
ac:vspace	the white space on the top and bottom of an image
ac:hspace	the white space on the left and right of an image

Tables

Format Type

In Confluence 3.5 and below

In Confluence 4.0 and above

What you will get

Two column, two row (top header row)

||Table Heading Cell 1||Table Heading Cell 2||
|Normal Cell 1|Normal Cell 2|

<table>
  <tbody>
    <tr>
      <th>Table Heading Cell 1</th>
      <th>Table Heading Cell 2</th>
    </tr>
    <tr>
      <td>Normal Cell 1</td>
      <td>Normal Cell 2</td>
    </tr>
  </tbody>
</table>

Table Heading Cell 1	Table Heading Cell 2
Normal Cell 1	Normal Cell 2

Two column, three rows, 2nd and third with merged cells in first row

N/A

<table>
  <tbody>
    <tr>
      <th>Table Heading Cell 1</th>
      <th>Table Heading Cell 2</th>
    </tr>
    <tr>
      <td rowspan="2">Merged Cell</td>
      <td>Normal Cell 1</td>
    </tr>
    <tr>
      <td colspan="1">Normal Cell 2</td>
    </tr>
  </tbody>
</table>

Table Heading Cell 1	Table Heading Cell 2
Merged Cell	Normal Cell 1
Merged Cell	Normal Cell 2

Miscellaneous

Format Type	In Confluence 3.5 and below	In Confluence 4.0 and above
Emoticons	:)	<ac:emoticon ac:name="smile" />
	:(	<ac:emoticon ac:name="sad" />
	:P	<ac:emoticon ac:name="cheeky" />
	:D	<ac:emoticon ac:name="laugh" />
	;)	<ac:emoticon ac:name="wink" />
	(y)	<ac:emoticon ac:name="thumbs-up" />
	(n)	<ac:emoticon ac:name="thumbs-down" />
	(i)	<ac:emoticon ac:name="information" />
	(/)	<ac:emoticon ac:name="tick" />
	(x)	<ac:emoticon ac:name="cross" />
	(!)	<ac:emoticon ac:name="warning" />

Resource Identifiers

Resource identifiers are used to describe "links" or "references" to resources in the storage format. Examples of resources include pages, blog posts, comments, shortcuts, images and so forth.

Resource	Resource identifier format
Page	<ri:page ri:space-key="FOO" ri:content-title="Test Page"/> Notes: `ri:space-key`: (optional) denotes the space key. This can be omitted to create a relative reference `ri:content-title`: (required) denotes the title of the page
Blog Post	<ri:blog-post ri:space-key="FOO" ri:content-title="First Post" ri:posting-day="2012/01/30" /> Notes: `ri:space-key`: (optional) denotes the space key. This can be omitted to create a relative reference `ri:content-title`: (required) denotes the title of the page `ri:posting-day`: (required) denotes the posting day. The format is YYYY/MM/DD.
Attachment	<ri:attachment ri:filename> ... resource identifier for the container of the attachment ... </ri:attachment> Notes: `ri:filename`: (required) denotes the name of the attachment the body of the `ri:attachment` element should be a resource identifier denoting the container of the attachment. This can be omitted to create a relative attachment reference (similar to [foo.png] in wiki markup). Examples: Relative Attachment Reference <ri:attachment ri:filename="happy.gif" /> Absolute Attachment Reference <ri:attachment ri:filename="happy.gif"> <ri:page ri:space-key="TST" ri:content-title="Test Page"/> </ri:attachment>
URL	<ri:url ri:value="http://example.org/sample.gif"/> Notes: `ri:value`: (required) denotes the actual URL value.
Shortcut	<ri:shortcut ri:key="jira" ri:parameter="ABC-123"> Notes: `ri:key`: (required) represents the key of the Confluence shortcut `ri:parameter`: (required) represents the parameter to pass into the Confluence shortcut The example above is equivalent to `[ABC-123@jira]` in wiki markup.
User	<ri:user ri:username="fred"/> Notes: `ri:username`: (required) denotes the name of the user.
Space	<ri:space ri:space-key="TST"/> Notes: `ri:space-key`: (required) denotes the key of the space.
Content Entity	<ri:content-entity ri:content-id="123"/> Notes: `ri:content-id`: (required) denotes the id of the content.

Page tree

Confluence Storage Format

Intended Audience

Content Categories

Macros

Info Macro

Code Block Macro

Table of Contents Macro

Headings

Text Effects

Text Breaks

Lists

Links

A Note on Link Bodies

Images

Tables

Miscellaneous

Resource Identifiers