Convert ADOC to Markdown

Why Convert ADOC to Markdown?

Converting AsciiDoc to Markdown transforms your richly structured technical documentation into the most universally supported lightweight markup format on the web. While AsciiDoc excels at complex documentation with its advanced features, Markdown's simplicity and ubiquitous platform support make it the preferred choice for GitHub repositories, blogs, wikis, and everyday developer documentation.

Many technical writers and documentation teams start projects in AsciiDoc for its powerful features like include directives, admonitions, and conditional content. However, when sharing content with broader audiences or publishing on platforms that primarily support Markdown (such as GitHub Issues, pull requests, DEV.to, or static site generators like Jekyll and Hugo), converting to Markdown ensures maximum compatibility and reach.

The conversion maps AsciiDoc constructs to their closest Markdown equivalents: = headings become # headings, *bold* becomes **bold**, _italic_ becomes *italic*, source code blocks with language annotations translate to fenced code blocks with language hints, and AsciiDoc tables are restructured into GFM pipe-delimited tables. Admonitions are converted to styled blockquotes, and cross-references become standard links.

Once converted, the Markdown output is immediately usable on GitHub, GitLab, Bitbucket, documentation platforms like Read the Docs, note-taking apps like Obsidian and Notion, and virtually any modern content platform. This makes AsciiDoc to Markdown conversion essential for teams working across different documentation ecosystems.

Key Benefits of Converting ADOC to Markdown:

• Universal Compatibility: Markdown is supported on virtually every development and content platform
• GitHub Native: Perfect rendering in README files, Issues, Pull Requests, and GitHub Pages
• Simple Editing: Markdown's minimal syntax is easy for any contributor to read and edit
• Static Site Generators: Direct compatibility with Jekyll, Hugo, Gatsby, MkDocs, and Docusaurus
• Broad Tool Support: Hundreds of editors, parsers, and renderers available for Markdown
• Blog Publishing: Publish directly on DEV.to, Hashnode, Medium (via import), and personal blogs
• Note-Taking Integration: Works seamlessly with Obsidian, Notion, Bear, and other knowledge management tools

Practical Examples

Example 1: Technical Documentation Conversion

Input ADOC file (api-reference.adoc):

= REST API Reference
:toc:
:icons: font

== Authentication

All requests require an *API key* in the
`Authorization` header.

[source,bash]
----
curl -H "Authorization: Bearer TOKEN" \
  https://api.example.com/users
----

NOTE: Tokens expire after 24 hours.

|===
| Method | Endpoint | Description

| GET
| /api/users
| List all users

| POST
| /api/users
| Create a user

| DELETE
| /api/users/{id}
| Delete user
|===

Output Markdown file (api-reference.md):

# REST API Reference

## Authentication

All requests require an **API key** in the
`Authorization` header.

```bash
curl -H "Authorization: Bearer TOKEN" \
  https://api.example.com/users
```

> **Note:** Tokens expire after 24 hours.

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | /api/users | List all users |
| POST | /api/users | Create a user |
| DELETE | /api/users/{id} | Delete user |

Example 2: Book Chapter to Blog Post

Input ADOC file (chapter-intro.adoc):

== Getting Started with Docker

Docker simplifies application deployment
using _containerization_.

=== Prerequisites

You need the following installed:

. Docker Engine (v20+)
. Docker Compose
. A terminal application

TIP: On macOS, use Docker Desktop
for the easiest setup.

=== Your First Container

[source,bash]
----
docker run hello-world
----

IMPORTANT: Make sure the Docker daemon
is running before executing this command.

.Common Docker Commands
|===
| Command | Purpose

| `docker ps`
| List running containers

| `docker images`
| List downloaded images

| `docker stop`
| Stop a container
|===

Output Markdown file (chapter-intro.md):

## Getting Started with Docker

Docker simplifies application deployment
using *containerization*.

### Prerequisites

You need the following installed:

1. Docker Engine (v20+)
2. Docker Compose
3. A terminal application

> **Tip:** On macOS, use Docker Desktop
> for the easiest setup.

### Your First Container

```bash
docker run hello-world
```

> **Important:** Make sure the Docker daemon
> is running before executing this command.

**Common Docker Commands**

| Command | Purpose |
|---------|---------|
| `docker ps` | List running containers |
| `docker images` | List downloaded images |
| `docker stop` | Stop a container |

Example 3: Man Page Documentation to README

Input ADOC file (tool-docs.adoc):

= mytool(1)
:doctype: manpage

== Name

mytool - A command-line utility for
processing data files

== Synopsis

*mytool* [_OPTIONS_] _FILE_...

== Options

*-o, --output* _FILE_::
  Specify output file path.

*-f, --format* _FORMAT_::
  Set output format (json, csv, xml).

*-v, --verbose*::
  Enable verbose logging.

== Examples

Process a single file:

[source,bash]
----
mytool -f json input.csv
----

Process multiple files with verbose output:

[source,bash]
----
mytool -v -o results/ *.csv
----

Output Markdown file (tool-docs.md):

# mytool(1)

## Name

mytool - A command-line utility for
processing data files

## Synopsis

**mytool** [*OPTIONS*] *FILE*...

## Options

**-o, --output** *FILE*
: Specify output file path.

**-f, --format** *FORMAT*
: Set output format (json, csv, xml).

**-v, --verbose**
: Enable verbose logging.

## Examples

Process a single file:

```bash
mytool -f json input.csv
```

Process multiple files with verbose output:

```bash
mytool -v -o results/ *.csv
```

Frequently Asked Questions (FAQ)

Q: What is AsciiDoc and how does it differ from Markdown?

A: AsciiDoc is a lightweight markup language created in 2002 by Stuart Rackham, designed for writing technical documentation, books, and articles. Unlike Markdown, AsciiDoc supports advanced features out of the box including admonitions (NOTE, TIP, WARNING), include directives, cross-references, conditional content, and multi-part book structures. Markdown is simpler and more widely adopted, while AsciiDoc is more powerful for complex documentation projects.

Q: Will AsciiDoc admonitions (NOTE, TIP, WARNING) be preserved?

A: AsciiDoc admonitions do not have a direct Markdown equivalent, so they are converted to styled blockquotes. For example, "NOTE: Important info" becomes "> **Note:** Important info" in Markdown. While this preserves the content and visual emphasis, the distinct admonition styling (icons, colored boxes) that AsciiDoc provides through Asciidoctor will not be present in the Markdown output.

Q: How are AsciiDoc include directives handled?

A: AsciiDoc include directives (include::file.adoc[]) are a powerful feature that allows embedding content from other files. Since Markdown has no equivalent include mechanism, these directives are either resolved (if the included files are available) or noted as comments in the output. For best results, process your AsciiDoc through Asciidoctor first to resolve includes before converting to Markdown.

Q: Are source code blocks with syntax highlighting preserved?

A: Yes, AsciiDoc source code blocks with language annotations (e.g., [source,python] followed by ---- delimiters) are converted to Markdown fenced code blocks with the same language hint (e.g., ```python). The code content inside the block is preserved exactly as-is. Most Markdown renderers, including GitHub, will apply syntax highlighting based on the language hint.

Q: How are AsciiDoc tables converted to Markdown?

A: AsciiDoc tables (|=== syntax) are converted to GitHub Flavored Markdown pipe tables. Header rows are separated by |---|---| divider lines. Simple tables convert cleanly, but AsciiDoc's advanced table features like column spans, cell alignment specifiers, and nested content may require manual adjustment in the Markdown output since GFM tables have more limited functionality.

Q: Can I use the converted Markdown on GitHub?

A: Absolutely. The converter produces GitHub Flavored Markdown (GFM), which is fully compatible with GitHub README files, Issues, Pull Requests, Discussions, and GitHub Pages. The output includes GFM-specific features like fenced code blocks, pipe tables, and task lists where applicable. You can paste the output directly into any GitHub Markdown field or commit it as an .md file.

Q: What AsciiDoc features are lost during conversion?

A: Some advanced AsciiDoc features do not have direct Markdown equivalents and may be simplified or omitted during conversion. These include: include directives, conditional preprocessor directives (ifdef/endif), document attributes and variables, complex table formatting (column spans, alignment), sidebar and example blocks, custom roles and styling, and multi-part book structures (parts, appendices). The core content and structure are always preserved.

Q: Can I convert back from Markdown to AsciiDoc?

A: Converting from Markdown back to AsciiDoc is possible but will not restore AsciiDoc-specific features that were simplified during the original conversion. Markdown's simpler feature set means that admonitions, include directives, conditional content, and advanced table formatting cannot be automatically reconstructed. Always keep your original .adoc files if you need access to the full AsciiDoc functionality later.