Convert Markdown to AsciiDoc

Why Convert Markdown to AsciiDoc?

Converting Markdown to AsciiDoc is the natural progression when your documentation projects require more structure, richer semantics, and professional publishing capabilities. While Markdown is perfect for simple formatting tasks, AsciiDoc provides a full-featured markup language designed from the ground up for technical writing and book authoring.

AsciiDoc's semantic richness makes it ideal for complex documentation projects. Unlike Markdown's many incompatible flavors (CommonMark, GFM, MultiMarkdown, PHP Markdown Extra), AsciiDoc has a single, well-defined specification that ensures consistent rendering across all tools. This standardization is crucial for enterprise documentation where reliability and predictability are essential.

The Asciidoctor toolchain transforms AsciiDoc source into multiple output formats from a single source file. You can generate HTML5 pages, PDF documents, EPUB ebooks, DocBook XML, and man pages, all from the same AsciiDoc content. This single-source, multi-output approach saves significant time compared to maintaining separate documents for each format.

AsciiDoc's include directive system enables modular documentation architecture. You can break large documents into chapters, sections, and reusable components, then assemble them into different configurations for different audiences. This makes AsciiDoc the preferred choice for organizations managing large documentation sets with multiple contributors.

Key Benefits of Converting Markdown to AsciiDoc:

• Standardized Syntax: One specification, consistent behavior across all tools
• Multi-Output Publishing: Generate HTML, PDF, EPUB, and DocBook from one source
• Admonition Blocks: Native NOTE, TIP, WARNING, CAUTION, and IMPORTANT callouts
• Modular Architecture: Include directives for document composition
• Conditional Content: Tailor output for different audiences with ifdef/ifndef
• Document Attributes: Variables and metadata for dynamic content
• Professional Toolchain: Asciidoctor, Antora, and enterprise-grade tools

Practical Examples

Example 1: API Documentation

Input Markdown file (api.md):

# API Reference

## Authentication

All requests require an API key.

> **Important:** Keep your API key secret.

### GET /users

Returns a list of users.

```json
{
  "users": [
    {"id": 1, "name": "Alice"}
  ]
}
```

Output AsciiDoc file (api.asciidoc):

= API Reference

== Authentication

All requests require an API key.

IMPORTANT: Keep your API key secret.

=== GET /users

Returns a list of users.

[source,json]
----
{
  "users": [
    {"id": 1, "name": "Alice"}
  ]
}
----

Example 2: User Guide with Warnings

Input Markdown file (guide.md):

## Quick Start

1. Install the software
2. Configure settings
3. Run the application

> **Warning:** Backup your data before updating.

| Setting | Value | Description |
|---------|-------|-------------|
| timeout | 30s   | Max wait    |
| retries | 3     | Retry count |

Output AsciiDoc file (guide.asciidoc):

== Quick Start

. Install the software
. Configure settings
. Run the application

WARNING: Backup your data before updating.

|===
| Setting | Value | Description

| timeout
| 30s
| Max wait

| retries
| 3
| Retry count
|===

Example 3: Project Documentation

Input Markdown file (project.md):

# Project Overview

## Architecture

The system consists of three main components:

- **Frontend** - React application
- **Backend** - Node.js API server
- **Database** - PostgreSQL

For more details, see [Architecture Guide](arch.md).

Output AsciiDoc file (project.asciidoc):

= Project Overview

== Architecture

The system consists of three main components:

* *Frontend* - React application
* *Backend* - Node.js API server
* *Database* - PostgreSQL

For more details, see xref:arch.adoc[Architecture Guide].

Frequently Asked Questions (FAQ)

Q: What is the difference between ADOC and AsciiDoc?

A: There is no difference in the language itself. "AsciiDoc" is the name of the markup language, while ".adoc" and ".asciidoc" are both valid file extensions. The .adoc extension is shorter and more commonly used, while .asciidoc is the full name. Both are processed identically by Asciidoctor and other AsciiDoc tools.

Q: How does AsciiDoc compare to Markdown for technical writing?

A: AsciiDoc is significantly more capable for technical writing. It provides built-in admonition blocks (NOTE, TIP, WARNING), cross-references between documents, include directives for modular content, conditional processing, document attributes, callout annotations in code blocks, and a standardized specification. Markdown is simpler but lacks these features natively.

Q: Will my Markdown images and links be converted correctly?

A: Yes, Markdown images () are converted to AsciiDoc image macros (image::url[alt]), and Markdown links ([text](url)) are converted to AsciiDoc links (url[text]). Relative paths and absolute URLs are both preserved during conversion.

Q: Can I use AsciiDoc on GitHub?

A: Yes, GitHub renders .adoc and .asciidoc files natively in repositories, issues, and pull requests. You can use AsciiDoc for your README.adoc file just like README.md. However, some advanced features like include directives are not supported in GitHub's renderer since it processes files in isolation.

Q: What is Asciidoctor?

A: Asciidoctor is the modern, Ruby-based processor for the AsciiDoc markup language. It replaced the original Python-based AsciiDoc processor and is faster, more feature-rich, and actively maintained. Asciidoctor can generate HTML5, PDF (via asciidoctor-pdf), EPUB3, DocBook 5, and man pages from AsciiDoc source files.

Q: Is AsciiDoc used by any major organizations?

A: Yes, AsciiDoc is used by Red Hat for all product documentation, by the Eclipse Foundation for project documentation, by O'Reilly Media for book authoring, by the Spring Framework for its documentation, and by many other enterprise and open-source organizations for technical content.

Q: Can I generate PDF from AsciiDoc files?

A: Yes, Asciidoctor-PDF generates PDF documents directly from AsciiDoc source without requiring an intermediate format. You can customize the PDF output with themes that control fonts, colors, margins, headers, footers, and page layout. This makes AsciiDoc excellent for producing print-ready documentation.

Q: How do I handle Markdown-specific extensions during conversion?

A: GitHub Flavored Markdown (GFM) features like task lists, emoji shortcodes, and auto-linked URLs are converted to their AsciiDoc equivalents when available. Task lists become AsciiDoc checklists, fenced code blocks become source blocks, and tables are converted to AsciiDoc table syntax. Features without direct equivalents are approximated using the closest AsciiDoc construct.