This guide covers content preparation and formatting review for Confluence data. The recommendations aim to preserve meaning and readability. Features can vary by Confluence version, installed macros, and SIC configuration. Check the results using representative articles in your destination environment.

The most useful preparation rules

• Do an intermediate application such as confluence-markdown-exporter or an LLM to convert Confluence pages to markdown. Specifically Stack Overflow supported markdown.
• Do use real headings and native lists in Confluence. Keep body text as editable text and put each idea in a sensible reading order.
• Do simplify tables, expose hidden content, and write out information carried only by color, icons, or layout.
• Do preserve image captions, link labels, values, units, and references. These matter more than matching fonts or column widths.
• Don’t assume copying a page, seeing a good preview, or retaining an image URL proves that the saved article will be complete.
• Don’t convert an entire article into screenshots. Use images for visual material and keep explanatory text searchable and editable.

Choose the right treatment

Confluence content	Best destination treatment
Headings, paragraphs, lists, emphasis	Keep the structure using SIC formatting.
Simple data tables	Keep as Markdown tables with one header row.
Merged cells, columns, colored panels	Restructure into simple tables or labeled sections.
Macros, task controls, live reports	Replace with explicit text, a dated snapshot, or a link.
Diagrams, screenshots, attached documents	Preserve readable images; link supporting files from their approved storage location.

Preserve text structure and meaning

Headings and paragraphs

Do: Keep a clear heading hierarchy. Use the article title field for the page title, then consistent section and subsection levels in the body. A useful convention is level 2 for sections and level 3 for subsections. Preserve the relationships between sections when adapting an existing hierarchy.

Don’t: Make headings by enlarging or coloring ordinary text. Avoid tabs, repeated spaces, and empty lines used to position content visually.

## Access requests

Explain who can request access.

### Before you begin

List the prerequisites here.

Use a blank line between paragraphs. A single Return may become a space in Markdown. When a line break is essential within one paragraph, use two trailing spaces before the newline, or the supported <br> tag. Do not use repeated breaks to reproduce page layout.

Emphasis and special text

Meaning to preserve	SIC formatting
Bold and italic	**Important** and *emphasis*
Literal short text or an identifier	`exact text` using backticks
Strikethrough	<s>obsolete text</s>
Subscript and superscript	H<sub>2</sub>O and x<sup>2</sup>
A keyboard key	<kbd>Enter</kbd>

Do: Replace colored or highlighted meaning with words such as “Required,” “Warning,” or “Deprecated,” plus bold where helpful. Replace decorative underline with emphasis if needed. Retain the actual numbers and units in scientific text.

Don’t: Assume all Markdown dialects are interchangeable. In particular, do not rely on ~~text~~ for strikethrough; SIC’s Markdown renderer does not enable that extension. The supported HTML form above preserves it more reliably. Confluence wiki markup such as h2. and {panel} is not SIC formatting.

Lists and preserved whitespace

Do: Use numbered lists for steps and bullets for unordered items. Indent nested items consistently beneath the parent item. Check step order and numbering after conversion. If an identifier such as “Control A.1” must remain exact, keep it in the item’s text.

Use fenced blocks for existing code, logs, or preformatted text where spaces and line breaks carry meaning. Preserve their contents exactly. A supported language label can enable highlighting, but Confluence themes, titles, and line numbers do not transfer as equivalent formatting; put a useful title in ordinary text above the block.

Make tables simple and dependable

Confluence tables can include merged cells, cell colors, fixed widths, and rich content. SIC’s Markdown tables preserve rows, columns, a header row, and column alignment. They do not reproduce that full layout model.

Do

• Use a single header row with meaningful labels. Keep the same number of cells in every row. Repeat a grouping value in each row instead of relying on merged cells.
• Keep cell contents short: text, emphasis, inline code, and links. Move long paragraphs, lists, large images, and multi-line blocks below the table, linked by a clear label.
• Split large or complex tables by subject. Convert a vertical header into an ordinary first column with a label such as “Property.”
• Write status and units explicitly. For example, use “Approved” rather than a green cell, and “Days” in the column heading rather than relying on surrounding layout.

Don’t

• Do not preserve merged or nested tables, fixed pixel widths, cell shading, or multiple header tiers as raw Confluence HTML. The SIC allowlist does not preserve arbitrary table attributes such as row and column spans.
• Do not replace a normal data table with a screenshot merely to keep its appearance. Keep its values editable and searchable.
• Do not use tables to arrange unrelated paragraphs side by side. Use sections in reading order instead.

Example of a table prepared for migration

Before: “Payments” spans two rows in the System column; the Status cells are green and amber. After: repeat “Payments” and write the status in words.

| System | Check | Status |
| --- | --- | --- |
| Payments | Access review | Approved |
| Payments | Recovery drill | Pending |

Leave a blank line before and after a table when other content surrounds it. The separator row of dashes is required. For column alignment, use :--- for left, :---: for center, and ---: for right.

If a cell must contain a literal pipe character, the usual Markdown spelling is \|. Check that value again after saving and after switching editor modes, as escaping may change during that cycle. If it fails in your instance, move the value to text outside the table; do not silently change the value.

Replace layouts and macros with explicit content

Columns and page layouts

Do: Turn two- or three-column layouts into sequential sections. Choose the order in which a reader should act, and keep each image or note next to the text it explains. Use a simple comparison table only when the columns actually represent comparable data.

Don’t: Expect Confluence Section, Column, CSS, or layout wrappers to retain their widths or positioning. Do not describe something only as “the box on the right.”

Panels and status indicators

Do: Preserve the panel title and all its text. Use a clearly labeled paragraph or blockquote, such as the example below. Replace a Status macro with explicit text, such as “Status: Approved,” and include its date when the status is time-sensitive.

> **Warning — approval required**
> Obtain approval before changing production access.

Don’t: Rely on background colors or icons to distinguish a warning from an ordinary note. Do not rely on GitHub-style alert notation such as [!WARNING]; use an explicit bold label.

Expandable sections and tabs

Do: Open each Expand macro and inspect its full contents, including nested sections. Replace it with a heading followed by the complete text. Convert tabbed content into labeled sections in a logical order.

Don’t: Omit text because it is initially hidden. Do not use spoilers or raw <details> blocks as a general replacement for Expand. Use visible headings for predictable formatting; <details> is outside SIC’s supported HTML.

Included content and live reports

Do: For Include Page or Excerpt Include, decide whether the article needs a self-contained copy or a link to the maintained source. If you copy it, identify the source and the date of the snapshot. For Jira reports, Page Properties reports, charts, or other live macros, retain a useful plain-text summary and a link to the live record.

Don’t: Treat a copied macro result as something that will continue to refresh. Do not leave an empty macro placeholder where the article needs an explanation.

Tasks and mentions

Do: Replace task controls with ordinary list items that explicitly state “Open” or “Complete,” plus the owner and due date when meaningful. Keep people’s names readable and link to the appropriate profile if needed.

Don’t: Assume a copied checkbox remains interactive, an @mention notifies someone, or a due date retains its Confluence behavior.

Preserve images links and supporting material

Images and diagrams

Do: Retain the original readable image, place it close to its explanation, and preserve its caption as text. Add meaningful alternative text that describes what the image communicates. For diagrams, keep a text explanation of the flow, labels, and decisions readers need.

For draw.io, Gliffy, whiteboards, charts, and similar visual macros, a practical fallback is a clear image supported by explanatory text and a link to the editable original. This is a recommendation for preserving meaning; the visual macro itself will not become an editable SIC diagram.

Don’t: Assume keeping a Confluence image URL moves the underlying image. Confirm that the migrated article’s readers can load it and that the image will remain available after Confluence is retired. Avoid blurry screenshots of whole pages, unexplained icons, and images whose essential labels are too small to read.


Figure 1. Each request requires manager approval.

The URLs shown in examples are placeholders. Replace them with the final working destination before publishing.

Files and embedded media

Do: Move PDFs, spreadsheets, slide decks, and other supporting attachments to the organization’s approved document store if Confluence will be retired. Link to them with the file’s title, type, and purpose. Include the important conclusion or instructions in the article itself.

Don’t: Confuse image support with general file attachment support. SIC does not provide arbitrary file attachments. An embedded Office document, PDF viewer, or video macro should become a descriptive link; include a useful summary or transcript where needed.

Links and article navigation

Do: Preserve descriptive link text and verify each destination. Point links at migrated SIC articles where replacements exist. Recreate the table of contents as a list of links to the final article headings if the article needs one.

SIC can generate heading links for articles. Use the actual heading link from the saved article instead of guessing its fragment. Recheck links after renaming or duplicating headings.

Don’t: Carry over Confluence anchor fragments, page-tree macros, attachment links, or “click here” text without checking them. A working source link does not establish that the new destination has the same address.

Equations and specialist notation

Use supported subscript and superscript for simple notation.Use a readable formula image with the formula’s meaning and variables explained in text. Apply the same review to specialist macros and custom symbols.

Review the saved article before signing it off

Use a small representative pilot before applying the same preparation rules to the full collection. Include at least one page with complex tables, one with diagrams or attachments, one with macros and hidden content, and one with nested lists or preformatted blocks. Use this pilot to confirm formatting behavior in your own environment.

Before migration

• Keep an original reference copy. Identify every meaningful color, panel, merged cell, image, link, and macro. Open hidden sections and check included content.
• Apply real headings and lists. Simplify layouts and tables. Add textual status labels and preserve captions, units, and definitions.
• Decide where images and attached files will live. Record which source links need replacement with final article or file links.

After migration

• Compare the saved article side by side with Confluence. Check every heading, paragraph, list item, table row, number, and unit—not just the first screen.
• Check that warnings remain visibly labeled, all expanded content is present, and static copies of live information are identified as snapshots.
• Read each table across and down. Check escaped pipes, alignment, repeated grouping labels, and cells that were formerly merged.
• Open images at a readable size and follow every article, heading, file, and external link as an intended reader.
• Check preformatted text for lost whitespace, altered quotation marks, missing lines, and accidental emphasis.
• Open the article for editing, make a harmless formatting change, save it, and review it again. If users will switch between Markdown and rich text, include that cycle in the pilot.
• Look at a narrow browser window as well as a normal desktop view. Fix content that depends on wide tables, tiny diagrams, or side-by-side placement.

Definition of a faithful result

All required knowledge is present and understandable; headings and relationships remain clear; numbers and literal text are correct; images and links work; and the article can be edited without losing structure. A change in font, color palette, panel border, or spacing is acceptable when it does not change meaning.

If a complex visual cannot be represented faithfully, retain an image or a link to the original alongside a readable explanation. Do not hide the loss by dropping material or substituting a screenshot for an otherwise editable article.

Using the editor during cleanup

Pasting existing documents is a useful starting point for cleanup, but table structure may need to be repaired. Review the saved article even when the initial paste looks correct.