Skip to content
All posts

Cross-Format Markdown: Confluence, BBCode, AsciiDoc & reStructuredText (2026)

A tutorial on bridging Markdown to and from other markup formats — Atlassian Confluence/Jira wiki markup, forum BBCode, AsciiDoc, and reStructuredText — with migration tips and gotchas.

Markdown rarely lives alone. Your team wiki runs on Confluence, an old forum wants BBCode, the docs team standardized on AsciiDoc, and a Python project uses reStructuredText. Moving content between these worlds by hand is miserable. This tutorial covers the cross-format converters tool group — bridging Markdown to and from Confluence, BBCode, AsciiDoc, and reStructuredText.

The converters

ConversionTool
Markdown → Confluence/JiraMarkdown to Confluence
Markdown → BBCodeMarkdown to BBCode
AsciiDoc ↔ MarkdownAsciiDoc ↔ Markdown
reStructuredText ↔ MarkdownreStructuredText ↔ Markdown

Part 1: Markdown → Confluence

Atlassian Confluence (and Jira) use their own wiki markup, not Markdown. The Markdown to Confluence tool translates:

  • Headings, paragraphs, blockquotes
  • Code fences → Confluence code macros
  • Links and images
  • Lists
  • GFM tables → Confluence tables

Workflow

  1. Write in Markdown (editor).
  2. Convert with Markdown to Confluence.
  3. Paste the wiki markup into Confluence (use the wiki-markup insert option).

This lets engineers draft in familiar Markdown and publish to a Confluence-based team wiki without learning Atlassian syntax. If you also convert plain content (not full pages), the dedicated converter handles the common 90% — complex macros still need manual touch-up.

Part 2: Markdown → BBCode

Classic forums (phpBB, vBulletin, MyBB) run on BBCode — [b]bold[/b], [code]…[/code]. The Markdown to BBCode tool converts:

  • **bold** → [b]bold[/b]
  • *italic* → [i]italic[/i]
  • Headings, lists, code fences
  • Links → [url=…]…[/url]
  • Images → [img]…[/img]
  • Blockquotes → [quote]…[/quote]

Perfect for cross-posting a Markdown-written guide to a community forum that predates Markdown. BBCode has no tables, so GFM tables are flattened or need manual handling.

Part 3: AsciiDoc ↔ Markdown

AsciiDoc is richer than Markdown (used by O'Reilly, many docs teams) and the conversion is bidirectional. The AsciiDoc ↔ Markdown tool translates:

  • Headings (= levels ↔ # levels)
  • Source blocks ↔ fenced code
  • Inline formatting, links, images
  • Blockquotes and lists

Markdown → AsciiDoc when joining an AsciiDoc-based docs project; AsciiDoc → Markdown when migrating to a Markdown system. AsciiDoc-specific features (includes, attributes, complex tables) may need manual fixes — convert the bulk, then polish.

Part 4: reStructuredText ↔ Markdown

reStructuredText (RST) is the Python/Sphinx documentation standard. The reStructuredText ↔ Markdown tool bridges:

  • Headings (RST underline style ↔ ATX #)
  • Code blocks (.. code-block:: ↔ fences)
  • Links and images

Common scenario: a Python project moving from Sphinx/RST to an MkDocs/Markdown setup, or vice versa. As with AsciiDoc, directives and roles unique to RST need manual attention after the automated pass.

Migration strategy: convert the bulk, polish the rest

No cross-format converter is 100% — the formats have genuinely different feature sets. The reliable approach:

  1. Convert the bulk with the appropriate tool (handles the common 90%).
  2. Normalize the Markdown side with the formatter.
  3. Audit with the link checker and heading audit — conversions often shift heading levels and break relative links.
  4. Manually fix format-specific features (Confluence macros, RST directives, AsciiDoc includes).
  5. Verify the result renders correctly in the previewer (for the Markdown direction).

Choosing a canonical format

When bridging formats long-term, pick one canonical source and generate the rest:

  • Markdown as source is the most portable — it converts cleanly to HTML, PDF, Confluence, BBCode, and (mostly) AsciiDoc/RST.
  • Keep the Markdown in Git (docs-as-code) and run conversions as a publish step.

This avoids the trap of maintaining the same content in four formats by hand.

Common mistakes

1. Expecting a perfect 1:1 conversion. Formats differ — convert the bulk, then polish.

2. Ignoring shifted headings. Conversions often change levels — run the heading audit after.

3. Broken relative links. Path conventions differ — re-check with the link checker.

4. Tables in BBCode. BBCode has none — flatten or restructure GFM tables.

5. Maintaining four formats by hand. Pick a canonical source (Markdown) and generate the rest.

Quick reference

TargetTool
Confluence / JiraMarkdown to Confluence
Forum BBCodeMarkdown to BBCode
AsciiDoc (both ways)AsciiDoc ↔ Markdown
reStructuredText (both ways)RST ↔ Markdown

Markdown is the best hub format in a multi-markup world. Convert the bulk with the cross-format tools, polish the format-specific bits by hand, and keep one canonical Markdown source — so content moves between Confluence, forums, AsciiDoc, and RST without a manual rewrite each time.

Written by Markdown Viewer Team. Found this useful? Try the editor →

Keep reading

Hand-picked articles related to this one.