How to format markdown for confluence wiki-markup pasting
- Step 1Paste or upload your doc — Use Paste text for a section, or Upload file for a full
.mdpage. Single file only — to combine several Markdown files into one page, merge them first with md-merger. - Step 2Click Run — The transform stashes fenced code, then rewrites headings, emphasis, lists, links, blockquotes, and rules in fixed order. There are no options.
- Step 3Review the wiki markup — Confirm headings became
h1./h2.and code samples became{code}macros. Any GFM tables will look unchanged — that is expected. - Step 4Copy the output — Click Copy to put the full wiki-markup string on your clipboard.
- Step 5Open Confluence's Wiki Markup dialog — In the Confluence editor choose Insert > Markup, set the type to Wiki Markup, paste, and Insert. Confluence converts the wiki markup into stored page content.
- Step 6Add panels, macros, and tables in Confluence — Convert generic
bq.quotes to{info}/{warning}panels if you want typed callouts, insert a{toc}macro, and rebuild any GFM tables as||header||rows — these are Confluence-side steps the converter does not perform.
Markdown to Confluence wiki mapping
The substitutions the transform performs. Confluence's Wiki Markup dialog accepts this same syntax.
| Doc element | Markdown | Wiki markup out |
|---|---|---|
| Page heading | # Overview | h1. Overview |
| Sub-heading | ## Setup | h2. Setup |
| Bold term | **required** | *required* |
| Italic term | _optional_ | _optional_ |
| Inline config key | MAX_RETRIES | {{MAX_RETRIES}} |
| Code sample | ` yaml … ` | {code:yaml}…{code} |
| Cross-page link | [API docs](https://wiki/api) | [API docs|https://wiki/api] |
| Bullet list | - item | * item |
| Numbered list | 1. step | # step |
| Blockquote / note | > Note this | bq. Note this |
| Section divider | --- | ---- |
Confluence features the converter does NOT add
These are Confluence concepts with no Markdown equivalent — do them after pasting.
| Confluence feature | Why it isn't converted | How to add it |
|---|---|---|
Typed panels {info} / {warning} / {note} | Markdown has only one blockquote; it becomes generic bq. | Replace bq. with {info}…{info} etc. in the wiki dialog |
Table of contents {toc} | Not a Markdown construct | Insert the Table of Contents macro in Confluence |
| GFM tables | No table handling in the transform | Rebuild as ||Col1||Col2|| + |a|b| |
Expand / collapse {expand} | Not a Markdown construct | Wrap content in {expand}…{expand} after paste |
| Status lozenges, mentions | Confluence-native, not Markdown | Add via the Confluence editor toolbar |
Input limits by tier
Long knowledge-base pages can hit the character cap before the file-size cap.
| Tier | Max size | Max characters | Files / run |
|---|---|---|---|
| Free | 1 MB | 500,000 | 1 |
| Pro | 10 MB | 5,000,000 | 1 used |
| Pro + Media | 50 MB | 20,000,000 | 1 used |
| Developer | 500 MB | Unlimited | 1 used |
Cookbook
Documentation fragments before and after conversion, plus the Confluence-side steps to finish the page.
A runbook section with heading, note, and command
Heading becomes h2., the blockquote note becomes bq., and the inline command becomes a {{…}} macro. Upgrade bq. to a {info} panel in Confluence if you want a styled callout.
Markdown in:
## Restart procedure
> Run during a maintenance window only.
Execute `systemctl restart api`.
Wiki out:
h2. Restart procedure
bq. Run during a maintenance window only.
Execute {{systemctl restart api}}.Code sample with a language tag
Fenced YAML becomes a {code:yaml} macro. Confluence shows the language label and applies its own monospace styling.
Markdown in:
```yaml
service:
retries: 3
timeout: 30s
```
Wiki out:
{code:yaml}
service:
retries: 3
timeout: 30s
{code}Nested procedure list
Numbered steps become #; a two-space-indented bullet detail under a step becomes **. Mixing # and * across levels follows the same two-space rule.
Markdown in: 1. Stop the service - Confirm no active jobs 2. Apply the patch Wiki out: # Stop the service ** Confirm no active jobs # Apply the patch
Comparison table left for manual rebuild
A GFM comparison table passes through untouched. Rebuild it as Confluence wiki table rows for proper rendering.
Markdown in: | Option | Cost | Latency | | ------ | ---- | ------- | | A | low | high | | B | high | low | Wiki out (unchanged): | Option | Cost | Latency | | ------ | ---- | ------- | | A | low | high | | B | high | low | Confluence form: ||Option||Cost||Latency|| |A|low|high| |B|high|low|
Cross-page link in a doc paragraph
Markdown link flips to the pipe form Confluence expects in the Wiki Markup dialog.
Markdown in: See the [deployment guide](https://wiki/deploy) before proceeding. Wiki out: See the [deployment guide|https://wiki/deploy] before proceeding.
Edge cases and what actually happens
GFM tables are not converted
By designThe transform has no table logic; a GFM table passes through as raw pipe text and renders as plain monospaced lines in Confluence. Rebuild it in the editor as ||header||header|| plus |cell|cell| rows. This corrects earlier copy implying tables auto-convert.
Blockquotes become generic bq., not typed panels
Manual fixMarkdown has a single blockquote, so > text becomes bq. text. Confluence's {info}, {warning}, and {note} panels carry meaning Markdown can't express. After pasting, wrap the relevant content in the panel macro you want.
Macros like {toc} or {expand} are not generated
Manual fixTable-of-contents, expand/collapse, and status macros are Confluence-native and have no Markdown source. Add them in the Confluence editor after the wiki markup is inserted.
Pasted into the rich editor instead of the Wiki Markup dialog
Display issuePasting wiki markup straight into the Confluence editor body shows literal h1. and {code} text. Use Insert > Markup > Wiki Markup so Confluence interprets the syntax, then Insert.
Images become a link form, not an embed
Manual fix becomes ![diagram|url] because the link rule matches the bracketed part. For Confluence, attach the image to the page and reference it with !filename!, or paste the image into the editor directly.
Underscored config keys read as italic
Watch outA config key like read_timeout written in prose can render as italic in Confluence (_ means italic). Wrap such keys in inline code so they become {{read_timeout}} monospace and the underscores are safe.
Multi-line note quoted lazily
Watch outThe blockquote rule works line by line. A multi-line note where only the first line starts with > converts only that line to bq.. Prefix every line of the note with > in the source.
Empty input
ExpectedNo input yields an empty string. Paste the doc or select a file first.
Large page exceeds Free character cap
Tier limitA long knowledge-base page can pass 500,000 characters while still under 1 MB. Split the page or upgrade to Pro (5,000,000 characters). To combine smaller files into one page instead, use md-merger.
Frequently asked questions
Why not just use Confluence's Markdown paste?
Confluence Cloud's Markdown paste exists but is lossy on complex content (nested lists, code blocks, links). Wiki markup via Insert > Markup > Wiki Markup is more predictable, and this tool produces that wiki syntax. For long pages, merge sources with md-merger first.
Are info/warning/note panels supported?
Not automatically. Markdown has only one blockquote type, so > text becomes generic bq. text. After pasting, wrap the content in {info}…{info}, {warning}…{warning}, or {note}…{note} in the Confluence editor to get a typed panel.
Can the tool insert a {toc} macro?
No. The table-of-contents macro is a Confluence feature with no Markdown equivalent. Insert the Table of Contents macro in Confluence after pasting; your h1./h2. headings give it the structure it needs.
Do GFM tables convert to Confluence tables?
No. Tables pass through as plain pipe text. Rebuild them as ||header||header|| + |cell|cell| in the editor. If your source table is malformed, md-table-repair can normalize it on the Markdown side first.
What happens to my code samples?
Fenced code becomes a {code:lang}…{code} macro (or {code} with no language). Confluence renders it with the language label and monospace styling. Everything inside the fence is preserved exactly — no characters are reinterpreted.
How do links convert for cross-page references?
[text](url) becomes [text|url], the pipe form Confluence's Wiki Markup dialog expects. External URLs stay clickable. For internal page links you can also use Confluence's link picker after pasting.
Are there any options to configure?
No. The transform is deterministic with no settings. To shape the output, edit the Markdown first. Sibling tools like md-toc-generator and md-lint help prep the source.
Is my documentation uploaded anywhere?
No. The conversion runs in your browser on a string. Internal docs, hostnames, and any credentials in a runbook never reach a server. Only an anonymous run counter is logged for dashboard stats.
What output do I get and how do I save it?
Plain wiki-markup text. Copy it to the clipboard or Download a -jira.txt file (original name plus -jira.txt). Paste the copied text into Confluence's Insert > Markup > Wiki Markup dialog.
How long a page can I convert at once?
Free: 1 MB / 500,000 characters per file. Pro: 10 MB / 5,000,000 characters. The character cap is independent of byte size, so a dense page can hit it first. The tool converts one file per run; merge multiple files with md-merger beforehand.
How do I keep the Markdown source and the Confluence page in sync?
Treat the Markdown in Git as the source of truth and re-run this conversion when it changes. Save the -jira.txt output alongside the source so reviewers can see both. The tool itself does no diffing — for that compare two versions with md-diff.
Where do I go for non-Confluence targets?
For a Jira ticket use the Jira wiki guide; for Slack use md-to-slack; for a downloadable HTML page use md-to-html; for a Word export use md-to-docx.
Privacy first
All Markdown processing runs locally in your browser using JavaScript. No file is ever uploaded to JAD Apps servers — only metadata counters are saved for signed-in dashboard stats.