Convert RST to AsciiDoc

Why Convert RST to AsciiDoc?

Converting reStructuredText (RST) to AsciiDoc is a common step when migrating documentation from the Python/Sphinx ecosystem to the more versatile Asciidoctor toolchain. While RST excels at Python documentation via Sphinx, AsciiDoc offers a broader range of output formats and a syntax that many technical writers find more intuitive and readable.

AsciiDoc was designed from the ground up for writing technical content, from simple articles to full-length books. Its syntax maps naturally to DocBook XML, which means your documents can be published as HTML, PDF, EPUB, man pages, and more -- all from a single source. Publishers like O'Reilly Media use AsciiDoc as their primary authoring format for technical books.

The migration from RST to AsciiDoc is particularly beneficial when your project outgrows the Python ecosystem. AsciiDoc's Asciidoctor processor is available in Ruby, Java (AsciidoctorJ), and JavaScript (Asciidoctor.js), making it a truly cross-platform solution. Additionally, the Antora documentation site generator provides a modern alternative to Read the Docs with multi-repository documentation support.

AsciiDoc also provides powerful features that RST lacks or implements differently, including conditional content inclusion (ifdef/ifndef), document attributes for configuration, built-in admonition blocks, and native support for complex table layouts. These features make AsciiDoc especially well-suited for large-scale documentation projects where content reuse and conditional output are important.

Key Benefits of Converting RST to AsciiDoc:

• Simpler Syntax: AsciiDoc's heading and formatting syntax is more intuitive than RST's underline-based approach
• Multi-Format Output: Generate HTML, PDF, EPUB, DocBook, and man pages from a single source
• Book Publishing: Industry-standard format for technical books (used by O'Reilly Media)
• Conditional Content: Include or exclude content based on attributes and output targets
• Cross-Platform Tooling: Asciidoctor runs on Ruby, Java, and JavaScript
• Modern Documentation Sites: Antora provides multi-repository documentation capabilities
• Active Community: Growing ecosystem with extensions, themes, and integrations

Practical Examples

Example 1: Document Structure and Headings

Input RST file (guide.rst):

Installation Guide
==================

Prerequisites
-------------

Before installing, ensure you have:

* Python 3.8 or later
* pip package manager
* Virtual environment (recommended)

.. note::
   On Windows, use ``py`` instead of ``python3``.

Quick Start
-----------

Install the package::

   pip install myproject

Output AsciiDoc file (guide.adoc):

= Installation Guide

== Prerequisites

Before installing, ensure you have:

* Python 3.8 or later
* pip package manager
* Virtual environment (recommended)

NOTE: On Windows, use `py` instead of `python3`.

== Quick Start

Install the package:

[source,shell]
----
pip install myproject
----

Example 2: Code Blocks and Cross-References

Input RST file (api.rst):

API Reference
=============

.. _configuration-section:

Configuration
-------------

.. code-block:: python

   from myproject import Config

   config = Config(
       debug=True,
       log_level="INFO"
   )

See :ref:`configuration-section` for details.

.. warning::
   Do not use ``debug=True`` in production.

Output AsciiDoc file (api.adoc):

= API Reference

[[configuration-section]]
== Configuration

[source,python]
----
from myproject import Config

config = Config(
    debug=True,
    log_level="INFO"
)
----

See <<configuration-section>> for details.

WARNING: Do not use `debug=True` in production.

Example 3: Tables and Admonitions

Input RST file (comparison.rst):

Feature Comparison
==================

+----------------+--------+---------+
| Feature        | Free   | Premium |
+================+========+=========+
| Basic support  | Yes    | Yes     |
+----------------+--------+---------+
| Priority email | No     | Yes     |
+----------------+--------+---------+
| Custom themes  | No     | Yes     |
+----------------+--------+---------+

.. tip::
   Upgrade to Premium for priority support.

.. image:: logo.png
   :alt: Project Logo
   :width: 200px

Output AsciiDoc file (comparison.adoc):

= Feature Comparison

[cols="3,1,1", options="header"]
|===
| Feature        | Free  | Premium
| Basic support  | Yes   | Yes
| Priority email | No    | Yes
| Custom themes  | No    | Yes
|===

TIP: Upgrade to Premium for priority support.

image::logo.png[Project Logo, 200]

Frequently Asked Questions (FAQ)

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

A: AsciiDoc is a lightweight markup language designed for writing technical documentation, articles, and books. While both RST and AsciiDoc serve similar purposes, AsciiDoc uses a more intuitive syntax (e.g., = for headings instead of underline characters) and natively supports multiple output formats through Asciidoctor. RST is tightly coupled with the Python ecosystem via Sphinx, whereas AsciiDoc is language-agnostic and widely used across different technology stacks.

Q: Will my RST directives be converted properly?

A: Most common RST directives have direct AsciiDoc equivalents. Code blocks (.. code-block::) become [source] blocks, admonitions (.. note::, .. warning::) become NOTE: and WARNING: blocks, images (.. image::) become image:: macros, and cross-references are converted to AsciiDoc anchor syntax. Some Sphinx-specific directives (like .. toctree::) may require manual adjustment as they rely on Sphinx's build system.

Q: Can I still use Sphinx after converting to AsciiDoc?

A: Not directly. Sphinx is designed to work with RST files. However, AsciiDoc has its own excellent documentation site generators. Antora is the most popular option, providing multi-repository documentation support, versioned docs, and a component-based architecture. You can also use Asciidoctor directly to generate HTML or PDF, or integrate with Jekyll, Hugo, or other static site generators.

Q: How are RST tables converted to AsciiDoc?

A: RST grid tables and simple tables are converted to AsciiDoc's table syntax using the |=== delimiter and pipe-separated columns. AsciiDoc tables support column width specifications (cols attribute), header rows, cell spanning, and nested content. The AsciiDoc table syntax is generally considered more readable and easier to maintain than RST's grid table format.

Q: What happens to inline RST markup during conversion?

A: RST inline markup is mapped to AsciiDoc equivalents: **bold** becomes *bold*, *italic* becomes _italic_, ``inline code`` becomes `inline code`, and interpreted text roles are converted where possible. Hyperlinks, footnotes, and substitution references are also translated to their AsciiDoc counterparts. Some custom RST roles may need manual review.

Q: Is AsciiDoc suitable for large documentation projects?

A: Absolutely. AsciiDoc was designed with large-scale documentation in mind. It supports file includes (include::), conditional processing (ifdef/ifndef), document attributes for variables and configuration, and modular document structures. Major organizations like Red Hat, the Eclipse Foundation, and Spring use AsciiDoc for their documentation. O'Reilly Media uses it as a primary authoring format for technical books.

Q: Can I convert AsciiDoc back to RST if needed?

A: Yes, tools like Pandoc support bidirectional conversion between AsciiDoc and RST. However, some AsciiDoc-specific features (conditional content, custom attributes, certain block types) may not have direct RST equivalents. It is recommended to keep a backup of your original RST files during the migration process until you are confident in the AsciiDoc versions.

Q: What tools do I need to work with AsciiDoc files?

A: The primary tool is Asciidoctor, available as a Ruby gem (gem install asciidoctor), a Java library (AsciidoctorJ), or a JavaScript package (asciidoctor.js). For editing, VS Code with the AsciiDoc extension provides live preview and syntax highlighting. IntelliJ IDEA has a built-in AsciiDoc plugin. For documentation sites, Antora is the recommended generator. For PDF output, use asciidoctor-pdf.