Convert MD to ADOC

Why Convert Markdown to AsciiDoc?

Converting Markdown to AsciiDoc is essential when you need to transition from simple documentation to professional-grade publishing workflows. While Markdown is excellent for quick notes and web content, AsciiDoc is specifically designed for comprehensive technical documentation, book publishing, and enterprise content that requires sophisticated formatting, cross-referencing, and multi-format output (HTML, PDF, EPUB, DocBook, man pages).

AsciiDoc's strength lies in its publishing capabilities. O'Reilly Media, one of the world's leading technical publishers, uses AsciiDoc as their standard format for writing books. The format supports document attributes (variables), file includes (reusable content), conditional content (platform-specific sections), admonition blocks (NOTE, TIP, WARNING, IMPORTANT, CAUTION), complex tables with cell spanning, source code with callout annotations, and automatic cross-references. AsciiDoctor, the modern Ruby-based processor, can convert AsciiDoc to beautifully formatted HTML5, PDF (via Asciidoctor-PDF), EPUB3, DocBook, man pages, and reveal.js presentations.

The conversion is particularly valuable when migrating content for professional publishing, creating comprehensive technical manuals, writing books, or building enterprise documentation systems that require consistent branding, multi-language support, or conditional content assembly. AsciiDoc's syntax is more verbose than Markdown but provides explicit control over document structure, making it ideal for large documentation projects with multiple contributors who need consistent formatting standards and advanced features like bibliography management, footnotes, index generation, and glossaries.

Practical Examples

Example 1: Technical Documentation with Admonitions

Input Markdown file (guide.md):

# Installation Guide

## Prerequisites

Make sure you have Java 11+ installed.

**Note:** Version 8 is not supported.

## Quick Start

```bash
./install.sh
```

Output AsciiDoc file (guide.adoc):

= Installation Guide

== Prerequisites

Make sure you have Java 11+ installed.

NOTE: Version 8 is not supported.

== Quick Start

[source,bash]
----
./install.sh
----

Example 2: Book Chapter with Cross-References

Input Markdown file (chapter1.md):

# Chapter 1: Introduction

Welcome to *AsciiDoc Mastery*.

See [Chapter 2](chapter2.md) for details.

## Key Concepts

- Documentation as Code
- Single Source Publishing
- Multi-format Output

Output AsciiDoc file (chapter1.adoc):

= Chapter 1: Introduction

Welcome to *AsciiDoc Mastery*.

See <> for details.

== Key Concepts

* Documentation as Code
* Single Source Publishing
* Multi-format Output

Example 3: API Documentation with Tables

Input Markdown file (api.md):

## API Methods

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET    | /users   | List users  |
| POST   | /users   | Create user |

> **Warning**: Authentication required!

Output AsciiDoc file (api.adoc):

== API Methods

[cols="1,1,2"]
|===
|Method |Endpoint |Description

|GET
|/users
|List users

|POST
|/users
|Create user
|===

WARNING: Authentication required!

Frequently Asked Questions (FAQ)

Q: What is AsciiDoc and why is it used for publishing?

A: AsciiDoc is a comprehensive plain-text markup language designed for writing technical documentation and books. Unlike Markdown (designed for web), AsciiDoc was created specifically for professional publishing. O'Reilly Media uses AsciiDoc for their technical books because it supports advanced features like document attributes, file includes, conditional content, callout annotations, and generates high-quality PDF, EPUB, and HTML output through AsciiDoctor.

Q: How does AsciiDoc syntax differ from Markdown?

A: AsciiDoc uses different syntax: headers use = signs (= Title, == Header) instead of #; emphasis uses asterisks for bold (*bold*) and underscores for italic (_italic_); links use link:url[text] instead of [text](url); code blocks use delimiters like ---- instead of ```; and AsciiDoc has built-in admonitions (NOTE:, WARNING:, TIP:) that don't exist in standard Markdown.

Q: Will code blocks convert correctly from Markdown to AsciiDoc?

A: Yes, Markdown fenced code blocks (```language) convert to AsciiDoc listing blocks with [source,language] attributes. AsciiDoc supports additional features like callout numbers for annotations, line highlighting, and include directives to embed external code files. The conversion preserves syntax highlighting language specifications.

Q: Can I publish books with AsciiDoc after conversion?

A: Absolutely! AsciiDoc is specifically designed for book publishing. After conversion, you can use AsciiDoctor to generate professional PDF books (via Asciidoctor-PDF), EPUB e-books, or submit to O'Reilly's Atlas platform. AsciiDoc supports book-specific features like front matter, part divisions, chapter numbering, bibliography, index, and glossary that Markdown lacks.

Q: How are Markdown tables converted to AsciiDoc?

A: Markdown pipe tables (| col1 | col2 |) convert to AsciiDoc table syntax using |=== delimiters. AsciiDoc tables are more powerful, supporting cell spanning, column alignment ([cols="1,2,3"]), header rows, footer rows, and CSV data embedding. The converter creates basic AsciiDoc tables that you can enhance with advanced features as needed.

Q: What are admonitions and will they be created during conversion?

A: Admonitions are special blocks for notes, tips, warnings, and cautions (NOTE:, TIP:, WARNING:, IMPORTANT:, CAUTION:). Standard Markdown doesn't have admonitions, so they won't be automatically created during conversion. However, if your Markdown uses blockquotes (> Note:) for warnings or notes, you may want to manually convert them to AsciiDoc admonitions after conversion to leverage their superior formatting and iconography.

Q: Can I use document attributes (variables) in AsciiDoc?

A: Yes! Document attributes are one of AsciiDoc's most powerful features. After conversion, you can add attributes like :author:, :version:, :toc:, :icons: to the document header, and use them throughout the text with {attribute-name}. This enables single-source publishing where you maintain one document and generate multiple versions (different products, versions, or audiences) by changing attribute values.

Q: Can I automate Markdown to AsciiDoc conversion in my workflow?

A: Yes, you can integrate MD to AsciiDoc conversion using Pandoc (pandoc -f markdown -t asciidoc input.md -o output.adoc) or Kramdoc (a Markdown to AsciiDoc converter). Many documentation teams use build scripts or CI/CD pipelines to convert Markdown source files to AsciiDoc for publishing. This allows writers to use Markdown's simplicity while benefiting from AsciiDoc's publishing capabilities.