When upgrading from Confluence 3.x to Confluence 4.x, the underlying storage format for your content will be migrated from a wiki markup-based format to a new XHTML-based format. This page describes the new storage format, and provides an opportunity for people to discuss the storage format and related ideas.
On this page:
] [ Macros ] [ Headings ] [ Text effects ] [ Text breaks ] [ Lists ] [ Links ] [ Images ] [ Tables ] [ Page layouts ] [ Resource identifiers ] [ Template variables ] [ Instructional Text ] [ Another page available for further discussion ]
Comments welcome
This page has attracted a lot of interest and a number of very valuable comments. Please have a read, to see the ideas that people have proposed.
Notes about the storage format
- You can view the Confluence storage format for a given page by choosing Tools > View Storage Format. This option is only available if one of the following is true:
- You are a Confluence administrator.
- Your Confluence site has the Confluence Source Editor plugin installed and you have permission to use the source editor.
- If you would like to edit the storage format for a page, your Confluence system administrator will need to install the Confluence Source Editor plugin.
Clarification of terminology: If you choose Tools > View Source, you will see the format used within the editor panel, not the storage format of the page.
We refer to the Confluence storage format as 'XHTML-based'. To be correct, we should call it XML, because the Confluence storage format does not comply with the XHTML definition. In particular, Confluence includes custom elements for macros and more. We're using the term 'XHTML-based' to indicate that there is a large proportion of HTML in the storage format.
Macros
See Confluence Storage Format for Macros.
Headings
Format type | In Confluence 3.5 and earlier | In Confluence 4.0 and later | What you will get | |
---|---|---|---|---|
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> | ||
Headings 4 to 6 are also available and follow the same pattern |
Text effects
Format type | In Confluence 3.5 and earlier | In Confluence 4.0 and later | 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> | <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} | <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 | ||
center-align | n/a | <p style="text-align: center;">centered text</p> | centered text | ||
right-align | n/a | <p style="text-align: right;">right aligned text</p> | right aligned text |
Text breaks
Format type | In Confluence 3.5 and earlier | In Confluence 4.0 and later | What you will get |
---|---|---|---|
New paragraph | Paragraph 1 | <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 | Line 1 Line 2 |
Horizontal rule | ---- | <hr /> | |
— symbol | --- | — | — |
– symbol | -- | – | – |
Lists
Format type | In Confluence 3.5 and earler | In Confluence 4.0 and later | What you will get |
---|---|---|---|
Unordered list – round bullets | * Round bullet list item | <ul> <li>round bullet list item</li> </ul> |
|
Ordered list (numbered list) | # Ordered list item | <ol> <li>numbered list item</li> </ol> |
|
Task Lists | [] Task list item | <ac:task-list> <ac:task> <ac:task-status>incomplete</ac:task-status> <ac:task-body>task list item</ac:task-body> </ac:task> </ac:task-list> |
|
Links
Format type | In Confluence 3.5 and earlier | In Confluence 4.0 and later | 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 (same page) | [Anchor Link|#anchor] | <ac:link ac:anchor="anchor"> <ac:plain-text-link-body> <![CDATA[Anchor Link]]> </ac:plain-text-link-body> </ac:link> | Anchor Link |
Anchor link (another page) | [Anchor Link|pagetitle#anchor] | <ac:link ac:anchor="anchor"> <ri:page ri:content-title="pagetitle"/> <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> |
A note about 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.
<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>
The markup tags permitted within the <ac:link-body> are <b>, <strong>, <em>, <i>, <code>, <tt>, <sub>, <sup>, <br> and <span>.
Images
Format type | In Confluence 3.5 and earlier | In Confluence 4.0 and later | 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> | ![]() |
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 earlier | In Confluence 4.0 and later | What you will get | |||||
---|---|---|---|---|---|---|---|---|
Two column, two row (top header row) | ||Table Heading Cell 1||Table Heading 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> |
| |||||
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> |
|
Page layouts
Confluence supports page layouts directly, as an alternative to macro-based layouts (using, for example, the section and column macros). This section documents the storage format XML created when these layouts are used in a page.
Notes:
- Page layouts were originally introduced in Confluence 4.2, and are not available in earlier versions of Confluence. If you are using Confluence 4.2 - 5.1 you should refer to the documentation for your version of Confluence:
- Pages with a layout created in the old format will be converted to 5.2 format.
- Confluence 5.2 provides more flexible layouts with a more concise storage format.
Element name | In Confluence 5.2 and later | Attributes |
---|---|---|
ac:layout | Indicates that the page has a layout. It should be the top level element in the page. | None |
ac:layout-section | Represents a row in the layout. It must be directly within the
| ac:type |
ac:layout-cell | Represents a column in a layout. It must be directly within the ac:layout-section tag. There should be an appropriate number of cells within the layout-section to match the ac:type . | None |
The recognised values of ac:type
for ac:layout-section
are:
| Expected number of cells | Description |
---|---|---|
| 1 | One cell occupies the entire section. |
two_equal | 2 | Two cells of equal width. |
two_left_sidebar | 2 | A narrow (~30%) cell followed by a wide cell. |
two_right_sidebar | 2 | A wide cell followed by a narrow (~30%) cell. |
three_equal | 3 | Three cells of equal width. |
three_with_sidebars | 3 | A narrow (~20%) cell at each end with a wide cell in the middle. |
The following example shows one of the more complicated layouts from the old format built in the new. The word {content}
indicates where further XHTML or Confluence storage format block content would be entered, such as <p>
or <table>
tags.
<ac:layout> <ac:layout-section ac:type="single"> <ac:layout-cell> {content} </ac:layout-cell> </ac:layout-section> <ac:layout-section ac:type="three_with_sidebars"> <ac:layout-cell> {content} </ac:layout-cell> <ac:layout-cell> {content} </ac:layout-cell> <ac:layout-cell> {content} </ac:layout-cell> </ac:layout-section> <ac:layout-section ac:type="single"> <ac:layout-cell> {content} </ac:layout-cell> </ac:layout-section> </ac:layout>
Emoticons
Format type | In Confluence 3.5 and earlier | In Confluence 4.0 and later | What you will get |
---|---|---|---|
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:
|
Blog Post | <ri:blog-post ri:space-key="FOO" ri:content-title="First Post" ri:posting-day="2012/01/30" /> Notes:
|
Attachment | <ri:attachment ri:filename> ... resource identifier for the container of the attachment ... </ri:attachment> Notes:
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:
|
Shortcut | <ri:shortcut ri:key="jira" ri:parameter="ABC-123"> Notes:
|
User | <ri:user ri:username="fred"/> Notes:
|
Space | <ri:space ri:space-key="TST"/> Notes:
|
Content Entity | <ri:content-entity ri:content-id="123"/> Notes:
|
Template variables
This screenshot shows a simple template:
The template contains the following variables:
Variable name | Type | Values |
---|---|---|
$MyText | Single-line text | |
$MyMulti | Multi-line text | Size: 5 x 100 |
$MyList | List | List items: Apples,Pears,Peaches |
The XML export produces the following code for the template:
<at:declarations> <at:string at:name="MyText" /> <at:textarea at:columns="100" at:name="MyMulti" at:rows="5" /> <at:list at:name="MyList"> <at:option at:value="Apples" /> <at:option at:value="Pears" /> <at:option at:value="Peaches" /> </at:list> </at:declarations> <p>This is Sarah's template</p> <p>A single-line text variable: <at:var at:name="MyText" /></p> <p>A multi-line text variable: <at:var at:name="MyMulti" /></p> <p>A selection list: <at:var at:name="MyList" /></p> <p>End of page.</p>
Instructional Text
Instructional text allows you to include information on how to fill out a template for an end-user (the person using creating a page from the template). Instructional text will:
- automatically clear all instructional text as the user types in a specific text block, and
- automatically trigger a @mention prompt for user selection (for 'mention' type instructional text).
Screenshot: Example of instructional text.
<ul> <li><ac:placeholder>This is an example of instruction text that will get replaced when a user selects the text and begins typing.</ac:placeholder></li> </ul> <ac:task-list> <ac:task> <ac:task-status>incomplete</ac:task-status> <ac:task-body><ac:placeholder ac:type="mention">@mention example. This placeholder will automatically search for a user to mention in the page when the user begins typing.</ac:placeholder></ac:task-body> </ac:task> </ac:task-list>
Another page available for further discussion
A new page is available as a place to continue discussions: Confluence 4 further discussion.
Please feel free to add your comments anywhere. We are not shutting down discussion on this page. We are supplying the new page to alleviate the problems caused by slow response on this page, due to the number of comments here.
Attachments:







