Free online ASCIIDOC to RST converter

A Sphinx or Docutils project requires reStructuredText files, but the source documentation is written in AsciiDoc. Converting it preserves reusable documentation as .rst files for editing, version control, and Python documentation builds.

What the ASCIIDOC format is

AsciiDoc is a lightweight markup language for manuals, README files, books, API documentation, and technical websites. Files commonly use .adoc or .asciidoc extensions and are created or processed by Asciidoctor, AsciiDoc, Antora, and documentation build systems that embed AsciiDoc. Its syntax includes headings, attributes, cross-references, admonitions, tables, source-code blocks, includes, and macros.

What the RST format is

reStructuredText, usually abbreviated RST, is a plain-text markup format used by Docutils, Sphinx, Python package documentation, and some static-site generators. It supports structured headings, directives, roles, footnotes, references, tables, literal code blocks, and included files. RST is the native source format for Sphinx, so it is appropriate when a documentation project already depends on conf.py, Sphinx directives, or the Python documentation toolchain.

How to actually convert ASCIIDOC to RST

The most reliable command-line workflow is to let Asciidoctor interpret the source, emit DocBook XML, and let Pandoc write RST:

1. Install Asciidoctor and Pandoc using your operating system's package manager or the projects' installation instructions.
2. Change to the directory containing the source file and verify that referenced images and included files are available.
3. Run the conversion pipeline:

asciidoctor -b docbook5 -o - manual.adoc | pandoc -f docbook -t rst -o manual.rst

Replace manual.adoc and manual.rst with the actual filenames. Asciidoctor processes attributes, conditionals, includes, and AsciiDoc syntax before Pandoc converts the resulting DocBook structure. For a separate intermediate file, use asciidoctor -b docbook5 -o manual.xml manual.adoc, followed by pandoc -f docbook -t rst -o manual.rst manual.xml.

You can also convert the file for free on the 101convert.com website without installing software. Check the generated RST manually before adding it to a Sphinx project.

Quality and compatibility limits

This is a structural conversion rather than a one-to-one syntax substitution. AsciiDoc attributes, custom macros, Antora resource IDs, complex tables, embedded content, and Asciidoctor extensions may have no direct RST equivalent. DocBook intermediate output can also alter cross-reference targets, image paths, admonitions, and code-block options.

Build the result with sphinx-build or Docutils and correct warnings about unknown directives, unresolved references, malformed tables, and missing images. RST headings use underlines rather than AsciiDoc heading markers, and Sphinx-specific directives such as .. toctree:: usually require manual insertion after conversion.