About AsciiDoc → HTML

Convert AsciiDoc markup to HTML with structure preservation. Part of the DevTools Surf developer suite. Browse more tools in the Converters collection.

Use Cases

• Convert AsciiDoc technical documentation to HTML for web publishing
• Preview AsciiDoc files without installing Asciidoctor locally
• Extract HTML from AsciiDoc book chapters for single-page embedding
• Verify AsciiDoc markup renders correctly before committing to a docs repo

Tips

• Include the ':toc:' attribute at the top of the document to auto-generate a table of contents in the HTML output
• Use [source,python] blocks with syntax highlighting attribute to get code-fenced output with language hints
• AsciiDoc's include directives are not executed client-side — inline all content before pasting for correct conversion

Fun Facts

• AsciiDoc was created by Stuart Rackham in 2002, predating Markdown by two years. It was designed from the start for technical book-length documents, not blog posts.
• O'Reilly Media adopted AsciiDoc as its primary authoring format for technical books in the early 2010s. Many well-known programming books are written in AsciiDoc and converted to PDF/EPUB via Asciidoctor.
• Asciidoctor, the modern Ruby-based AsciiDoc processor, processes documents at over 1,000 pages per second — fast enough for large documentation sets where Markdown tools sometimes struggle.

FAQ

Is AsciiDoc the same as Markdown?

No. AsciiDoc is a more feature-rich format designed for long-form technical documents: it has native support for footnotes, cross-references, includes, sidebars, and output to multiple formats. Markdown is simpler and better suited for short-form web content.

Does the converter support Asciidoctor extensions?

No — client-side conversion handles core AsciiDoc syntax. Asciidoctor extensions (diagram, pdf) run server-side and are not supported here. Use the Asciidoctor CLI for those.

Can I convert the other way — HTML to AsciiDoc?

This tool converts AsciiDoc to HTML only. For the reverse direction, Pandoc supports HTML-to-AsciiDoc conversion via command line.