Chris Collins

Tools · dev

Markdown ↔ AsciiDoc converter

Convert Markdown (GitHub-flavoured, with alerts, footnotes and front matter) to AsciiDoc and back, see both rendered side by side, and get a report of everything that had to be approximated.

Added

Works with

How to use it

Paste a README or a post on the left and get the other format on the right, with both rendered underneath. Under that is the fidelity report: every place where the target format has no direct equivalent, what was done instead, and the source line it came from.

I wrote this because the site is AsciiDoc and most of what I paste in starts as Markdown — and because the established converters each get a few things quietly wrong. The tests compare this one with them on the same documents (see the end of this page).

How to use it

  1. Choose Markdown → AsciiDoc or AsciiDoc → Markdown, then paste, Open file… or pick one of the Examples. The conversion updates as you type. ⇄ Swap feeds the result back in the other way, which is a quick way to see what survives a round trip.

  2. Read the Fidelity report. approx. entries are things that could not be represented exactly (a table with spans becoming an HTML table, a multi-paragraph footnote joined into one line); note entries are choices worth knowing about. Click a line number to jump to it.

  3. Under the rendered result there is a line with Asciidoctor’s own warnings for the AsciiDoc side, so you can see the result is clean.

  4. Open in previewer ↗ sends the result to the Markdown and AsciiDoc previewer; Lint result ↗ sends it to the documentation linter. Diagrams in AsciiDoc ([graphviz], [mermaid]) render in the AsciiDoc studio.

Markdown → AsciiDoc

  • CommonMark plus GitHub’s extensions: tables (with alignment), task lists, strikethrough, footnotes, autolinks (including bare www. links), fenced code with info strings, front matter (YAML or TOML), HTML blocks and GitHub alerts (> [!NOTE] becomes NOTE:).

  • Text that AsciiDoc would read as markup is escaped: snake_case pairs, hash, {braces}, C++, a line ending in ` +, a paragraph starting with `NOTE:, <1> at the end of a code line (which would become a callout). This is where most converters go wrong.

  • Common HTML is turned into AsciiDoc: <details> into a collapsible block, <kbd> into kbd:[], <sub>/<sup>, <img> (with width and alignment), <video>, <a id> anchors and comments. Anything else is kept in a passthrough block and reported.

  • Links to headings (#getting-started) get an explicit id on the heading, because Asciidoctor’s own ids (_getting_started) differ from GitHub’s.

  • gitwebsite post header writes the header this site uses — :type:, :date:, :tags:, :summary: (from description), :status: draft (from draft: true) — and checks it with the same rules as the AsciiDoc studio.

  • Typographic replacements: Markdown shows ©, -- and …​ as typed, so by default they are escaped. Tick this to let Asciidoctor turn them into ©, — and ….

AsciiDoc → Markdown

  • Sections, attributes (including ones defined part-way through), conditionals (ifdef, ifndef, ifeval — evaluated with the document’s own attributes), admonitions (GitHub alerts or Note: quotes), source blocks with callouts (circled numbers in the code and a numbered list), tables (cols alignment and styles, implicit headers, CSV/DSV tables; spans and a| cells become HTML tables), cross references (to GitHub-style heading slugs), inline anchors, footnotes, images (with imagesdir), video (YouTube becomes a thumbnail link), description lists, sidebars, example and collapsible blocks, quotes and verse, kbd/btn/menu.

  • include:: can’t read your disk, so it is reported and left as a comment — unless you pick the included files with Include files…, which reads them in the browser and matches them by name.

How it compares

I ran the two established converters on the same test documents: kramdown-asciidoc 2.1.1 (Markdown → AsciiDoc) and downdoc 1.1.0 (AsciiDoc → Markdown). Where this tool differs, it is because their output renders differently from the source: kramdown-asciidoc leaves hash, xy and a trailing ` +` unescaped, turns a paragraph starting NOTE: into an admonition, makes <1> in code a callout, links [x](#cutting) to an id that doesn’t exist, drops a list’s start number and doesn’t know GitHub alerts; downdoc leaves footnotes, kbd:, video:: and ifeval as raw macros, ignores options="header", and garbles spanned and CSV tables. Where they agree with each other (title handling, list markers, callout numbering, <details>) this tool does the same. The comparisons are kept in the test file.

Privacy

Everything happens in your browser; nothing you paste is uploaded. The rendered views load marked 14.1.4 (about 40 KB), DOMPurify 3.2.4 (about 20 KB) and Asciidoctor.js 3.0.4 (about 1.2 MB) from the jsDelivr CDN the first time — the same versions the previewer uses. The conversion itself is this site’s own code and works without them.

Runs entirely in your browser — network requests go only to the services named on this page.