AsciiDoc

Definition

AsciiDoc is a lightweight, plain-text markup language for writing structured documentation, books, and articles, designed to be readable as-is while converting cleanly into HTML, PDF, EPUB, and other output formats. It extends the basic ideas behind Markdown with a richer syntax for tables, cross-references, admonitions, footnotes, and document metadata, aimed specifically at technical and long-form publishing rather than short web posts.

Overview

AsciiDoc addresses a gap that plain Markdown leaves open: producing complete, well-structured technical documents such as software manuals, books, and API references from a single plain-text source. Where Markdown intentionally stays minimal, AsciiDoc adds native support for document-level metadata, multi-level sectioning, admonition blocks, footnotes, and table structures that longer technical works need without falling back to embedded HTML. A document is written as plain text with a defined syntax for headings, lists, code blocks, and cross-references, then processed by a toolchain, most commonly Asciidoctor, which parses the source into an internal document model and renders it to HTML5, DocBook, PDF, or EPUB. Asciidoctor also supports extensions written in Ruby that add custom block types or processing steps, and it can be driven from build tools so documentation regenerates automatically as source files change. Compared to Markdown, AsciiDoc trades some of Markdown's ubiquity and simplicity for built-in features Markdown users typically need extensions or embedded HTML to get, such as native tables with column specifications, structured admonitions (note, tip, warning), and automatic table of contents generation. Compared to DocBook, which AsciiDoc can convert to, it trades DocBook's exhaustive XML schema for a much friendlier plain-text authoring experience while still reaching the same publishing outputs. In practice, AsciiDoc is the documentation format behind many large open-source and enterprise technical writing projects, including software reference manuals and O'Reilly-style technical books, because a single source file can be built into a searchable HTML site and a print-ready PDF from the same content. Teams store `.adoc` files in version control alongside code, run Asciidoctor as part of a documentation build pipeline, and often mix generated API content with hand-written narrative sections in the same document tree. The format's learning curve is gentler than DocBook but steeper than Markdown, since its fuller feature set means more syntax to learn, and its ecosystem, while solid, is smaller than Markdown's, so fewer tools and editors offer first-class AsciiDoc support out of the box. Teams writing short READMEs or simple web content are usually better served by Markdown's simplicity, while AsciiDoc earns its complexity on book-length or multi-format technical publishing where structure, cross-referencing, and multiple output targets matter. Teams that outgrow Markdown's limits, needing consistent tables, numbered figures, or a single source feeding both a documentation website and a downloadable PDF, tend to find the added AsciiDoc syntax pays for itself once a project spans more than a handful of pages.

Key Features

• Plain-text syntax that remains readable without any rendering step
• Native support for admonitions like note, tip, and warning blocks
• Built-in table syntax with column and cell formatting options
• Document-level metadata for authors, revision info, and attributes
• Converts to HTML5, PDF, EPUB, and DocBook from one source
• Multi-level sectioning suited to book-length technical documents
• Extensible through Asciidoctor plugins written in Ruby
• Supports footnotes, cross-references, and automatic table of contents

Use Cases

Alternatives

Frequently Asked Questions

Related in Programming