Markdown to Confluence

Use the free online converter for rich-text copying without installing anything.

Markdown pasted into Confluence Cloud can appear as literal text or code instead of formatted content. The Cloud editor does not accept wiki markup (Atlassian documentation). This package converts Markdown into rich-text HTML for Cloud paste, or wiki markup for Server/Data Center editors that accept it.

Install

Requires Node.js 20 or later. ESM only; the library also works in browser bundles.

npm install kalcify-markdown-to-confluence

Library

import {
  convertMarkdown,
  noticesFor,
  noticeText,
} from 'kalcify-markdown-to-confluence';

const result = convertMarkdown('# Hello\n\nA **bold** start.');
console.log(result.cloudHtml); // <h1>Hello</h1><p>A <strong>bold</strong> start.</p>
console.log(result.wikiMarkup); // h1. Hello\n\nA *bold* start.

for (const notice of noticesFor('cloud', result.notices)) {
  console.warn(noticeText(notice));
}

convertMarkdown(markdown) parses once and returns both outputs, counts, and notices. Counts cover headings, tables, code blocks, ordinary list items, tasks, links and images. Each notice has an id, target (cloud, wiki or both), and count. TypeScript exports include Conversion, ElementCounts, Notice, NoticeId and Target.

For Cloud, put cloudHtml on the clipboard as text/html, then paste into the editor. In a browser, call this from a click handler on HTTPS or localhost:

await navigator.clipboard.write([
  new ClipboardItem({
    'text/html': new Blob([result.cloudHtml], { type: 'text/html' }),
  }),
]);

Clipboard permissions and browser support apply. Copying the HTML source from a terminal does not create rich text. The output targets editor paste, not Confluence storage-format XML or an API upload payload. Review the pasted result in your editor.

CLI

npx kalcify-markdown-to-confluence input.md > output.html
npx kalcify-markdown-to-confluence --target wiki input.md > output.wiki
cat input.md | npx kalcify-markdown-to-confluence --target cloud

The default target is cloud. Omit the file, or use -, to read UTF-8 Markdown from stdin. Output goes to stdout with a trailing newline (empty input stays empty); notices for the selected target go to stderr. Use --help for usage. Invalid arguments or unreadable input exit with status 1.

Supported Markdown and limits

CommonMark plus GitHub Flavored Markdown: headings, paragraphs, bold, italic, strikethrough, inline and fenced code, nested lists, task lists, tables, quotes, rules, hard breaks, links, reference links, autolinks and images.

Conversion notices describe losses:

• Raw HTML is shown as code; comments are removed. Inline <br> becomes a line break.
• Footnotes become superscript labels with note text at the definition, without navigation.
• Relative image paths need manual upload/replacement in Confluence.
• Unsafe URL schemes become plain text. Links allow HTTP(S), mail and telephone; images allow HTTP(S).
• Table column alignment is discarded.
• Cloud lists containing only tasks use action-item HTML; tasks mixed with ordinary items keep text checkboxes.
• Wiki tasks keep text checkboxes. Code blocks, tables and quotes inside wiki list items are emitted after the item.
• Wiki backslashes that cannot be represented are dropped. Code containing both {code} and {noformat} needs manual correction.

Nested quotes are flattened. Wiki ordered lists start at 1. Images remain references; the package does not upload attachments or contact Confluence.

Development

npm ci
npm run typecheck
npm run check:architecture
npm test
npm run build
npm pack --dry-run

The converter and regression tests were extracted from Kalcify; the public entry point is src/convert.ts. Markdown decoding belongs to mdast-util-from-markdown with GFM extensions; both renderers, counts and notices derive from its tree. Public declarations are generated by TypeScript. CLI argument parsing belongs to Node's util.parseArgs; target narrowing happens at that boundary. Runtime dependencies are the four mdast/micromark packages used by the converter. No persistence, environment configuration or remote API is involved.

Build output is regenerated from src and never committed. MIT licensed; see LICENSE.