# Markdown ⇄ AsciiDoc Converter

Bidirectional converter between GitHub-Flavored Markdown and AsciiDoc — headings, tables, code blocks, admonitions, links, task lists and more, with side-by-side output and conversion notes.

> Canonical page: https://elysiatools.com/en/tools/markdown-asciidoc-converter

- **Category:** Format Conversion

- **Keywords:** markdown to asciidoc, asciidoc to markdown, antora migration, asciidoctor convert, documentation converter

## Overview

Line-based block parser with inline tokenizers, no external dependencies. Section levels shift by one (= is the AsciiDoc document title); link brackets invert ([text](url) ⇄ url[text]); code fences ⇄ [source,lang] + ----; GFM pipe tables ⇄ |=== with options="header" and alignment colspecs; NOTE/TIP/IMPORTANT/WARNING/CAUTION admonitions ⇄ GitHub alerts (> [!NOTE]; the legacy > **Note** form is recognized on input); task lists, footnotes, anchors and cross-references, hard line breaks and horizontal rules all round-trip. include::, {attributes} and conditional directives degrade to HTML comments with a visible note. Round-trip losslessness is not promised — the goal is a correct one-way migration.

## Inputs

- **Conversion direction** (select)
- **Source document** (textarea): Paste your Markdown (or AsciiDoc when converting back)…
- **Promote first H1 to document title** (checkbox)
- **Keep unresolved markup visible** (checkbox)

## When to use

- Migrating static documentation sets or README files from Markdown to AsciiDoc for Antora or Asciidoctor workflows.
- Exporting AsciiDoc technical manuals into standard GitHub-Flavored Markdown for repository hosting or platform publishing.
- Converting structured docs containing tables, code fences, alerts, and inline anchors without manually reformatting syntax.

## How it works

- Select the conversion direction: Markdown → AsciiDoc (`md2ad`) or AsciiDoc → Markdown (`ad2md`).
- Paste your raw markup into the source document editor and configure options like H1 document title promotion and unresolved tag retention.
- The line-based block parser and inline tokenizer map matching structures like link targets, table colspecs, admonition blocks, and code tags into the target syntax.

## Use cases

- Publishing Markdown developer guides to Antora component documentation sites using native AsciiDoc files.
- Translating legacy AsciiDoc API documentation into Markdown for GitHub wiki pages or static site generators.
- Standardizing mixed open-source contributor pull requests containing varied Markdown and AsciiDoc markup.

## Frequently asked questions

### How are Markdown links converted to AsciiDoc?

Markdown link brackets invert to AsciiDoc syntax, turning `[text](url)` into `url[text]` while escaping URLs containing special characters.

### What does the title promotion option do?

When enabled in Markdown to AsciiDoc conversion, the first `#` heading is promoted to a single `=` document title rather than a standard section title.

### How are GitHub Alerts and AsciiDoc admonitions mapped?

Blocks like `> [!NOTE]` or `> **Note**` convert to AsciiDoc `NOTE:` admonitions, and vice versa.

### What happens to AsciiDoc directives like include:: during export to Markdown?

Directives such as `include::`, attribute references, and conditional statements degrade into visible HTML comments so no context is silently lost.

### Can I convert GitHub-Flavored Markdown tables with column alignments?

Yes, Markdown pipe tables convert to AsciiDoc `|===` blocks with `options="header"` and corresponding alignment specifiers in `cols`.

## Related tools

- [Markdown to HTML Converter](https://elysiatools.com/en/tools/markdown-to-html): Convert Markdown text to HTML with customizable formatting options using Showdown
- [Markdown to Plain Text](https://elysiatools.com/en/tools/markdown-to-plain-text): Convert Markdown formatted text to plain text by removing all Markdown syntax and formatting
- [Figma iOS Android pt dp sp Responsive Design Spec Card](https://elysiatools.com/en/tools/figma-ios-android-pt-dp-sp-responsive-design-spec-card): Convert a Figma px value into iOS pt, Android dp/sp, web rem/vw with a fluid clamp() snippet, a density-bucket render table and a touch-target accessibility audit, as a developer spec card.
- [Hash Algorithm Comparator](https://elysiatools.com/en/tools/hash-algorithm-comparator): Hash the same input with MD5, SHA-1, SHA-256, SHA-512, BLAKE2b, and BLAKE3 at the same time and compare them side by side: output length, hex/Base64 digest, security status (broken / modern), and a relative speed benchmark. Great for teaching, choosing a hashing algorithm, or sanity-checking checksums.
- [OKR & KPI Tree Decomposer](https://elysiatools.com/en/tools/okr-tree-decomposer): Decompose an Objective into a weighted Department → Team → Personal tree with automatic progress roll-up. HTML tree + Markdown + CSV output.
- [AI Image to Markdown](https://elysiatools.com/en/tools/ai-image-to-markdown): Extract text from images and convert to markdown format using AI vision models
- [Serum Anion Gap (AG) Calculator](https://elysiatools.com/en/tools/anion-gap-calculator): Calculate the serum Anion Gap (AG) to classify metabolic acidosis. Standard formula AG = Na⁺ − Cl⁻ − HCO₃⁻ (mmol/L), or AG = Na⁺ + K⁺ − Cl⁻ − HCO₃⁻ with optional potassium. A high AG (≈ >12, or >20 with K⁺) indicates accumulation of unmeasured anions (lactic acidosis, ketoacidosis, renal failure, and toxins such as methanol/ethylene glycol, salicylates — mnemonic GOLD-MARK). A normal AG (8–12) during metabolic acidosis points to a hyperchloremic (normal-anion-gap) acidosis: diarrhea, renal tubular acidosis, saline resuscitation. A low AG (<3–6) is usually hypoalbuminemia, also hypercalcemia/hypermagnesemia, lithium, cationic IgG paraproteins, or bromide pseudo-hyperchloraemia. Optional albumin correction AG_corrected = AG + 2.5 × (4.0 − albumin g/dL) avoids missing a high-AG acidosis in hypoalbuminemia. Derived from Kraut CJASN 2007, Figge 1998, and MDCalc. Interpret with blood gas and full clinical context. Not medical advice.
- [Indented List to ASCII Tree](https://elysiatools.com/en/tools/ascii-tree-from-indented-list): Convert a 2-space / 4-space / Tab indented hierarchical list (Markdown bullets, -, *, 1. prefixes optional) into a copyable ASCII directory tree. Two styles: Unicode box-drawing (├──└──│) for GitHub/Discord and classic ASCII (|--\--|) for plain text. Toggles for full guide lines, trailing spaces, and bracketed leaf nodes like docs/\[api.md\].

## Samples

- [Markdown Samples](https://elysiatools.com/en/samples/markdown-samples): Markdown format examples from simple to complex document structures
- [Markdown Viewer Samples](https://elysiatools.com/en/samples/markdown-viewer-samples): Sample Markdown files for README preview, documentation rendering, and rich-text markup tests
- [Markdown Slide Deck Samples](https://elysiatools.com/en/samples/md-slide-deck-to-pdf): Remark/Marp style Markdown slide decks for testing PDF export layouts
- [PDF Samples](https://elysiatools.com/en/samples/pdf-samples): Generated PDF samples from tools dated 2026-02-01 to 2026-02-10