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
| Conversion | Tool |
|---|---|
| Markdown → Confluence/Jira | Markdown to Confluence |
| Markdown → BBCode | Markdown to BBCode |
| AsciiDoc ↔ Markdown | AsciiDoc ↔ Markdown |
| reStructuredText ↔ Markdown | reStructuredText ↔ 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
- Write in Markdown (editor).
- Convert with Markdown to Confluence.
- 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:
- Convert the bulk with the appropriate tool (handles the common 90%).
- Normalize the Markdown side with the formatter.
- Audit with the link checker and heading audit — conversions often shift heading levels and break relative links.
- Manually fix format-specific features (Confluence macros, RST directives, AsciiDoc includes).
- 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.
Related articles
- Docs-as-code guide — canonical-source workflows
- Convert tutorial — HTML/PDF conversions
- GitLab Markdown guide — another wiki-style target
- Format & clean up tutorial
- Audit & quality tutorial
Quick reference
| Target | Tool |
|---|---|
| Confluence / Jira | Markdown to Confluence |
| Forum BBCode | Markdown 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.
A tutorial on Markdown as a data format — convert JSON to tables or lists, sort and transpose tables, extract every code block as a file, and track task-list progress for content pipelines.
A tutorial on adding diagrams and equations to Markdown using ready-made libraries — browse and copy Mermaid templates and KaTeX/LaTeX equations, then validate them before you commit.
A tutorial for authoring and publishing polished Markdown — generate a table of contents, manage frontmatter, add reading-time and callouts, create README badges, and present from Markdown.