Convert AsciiDoc to HTML

Why Convert AsciiDoc to HTML?

Converting AsciiDoc to HTML is the most natural and common transformation for AsciiDoc content. AsciiDoc was designed from the ground up to produce high-quality HTML output, and its markup elements map directly to semantic HTML5 elements. The result is clean, standards-compliant web pages that are accessible, SEO-friendly, and ready for immediate publication on any web server or content management system.

Asciidoctor, the primary AsciiDoc processor, generates beautifully structured HTML5 with semantic elements like article, section, nav, aside, and figure. The output includes CSS classes for every structural element, making it straightforward to apply custom themes and styles. Built-in features like table of contents generation, section numbering, cross-references, and syntax-highlighted code blocks produce professional documentation without any additional tooling.

The AsciiDoc-to-HTML pipeline is central to many documentation workflows used by major organizations. Red Hat uses AsciiDoc for all product documentation, Spring Framework publishes its reference guides from AsciiDoc sources, and numerous open-source projects host AsciiDoc-generated HTML on GitHub Pages, ReadTheDocs, or custom documentation portals. The format's ability to produce consistently structured HTML from concise markup makes it a productivity multiplier for technical writing teams.

For static site generators like Antora, Jekyll, and Hugo, AsciiDoc serves as the content source that produces the HTML pages visitors see. The conversion handles everything from simple README files to multi-chapter books with thousands of pages, producing navigable, interlinked HTML with consistent styling throughout. Whether you are publishing a single-page API reference or an entire documentation site, AsciiDoc-to-HTML is the foundation of the workflow.

Key Benefits of Converting AsciiDoc to HTML:

• Semantic HTML5: Clean, standards-compliant output with proper element usage
• Syntax Highlighting: Source code blocks rendered with language-specific coloring
• Auto-Generated TOC: Interactive table of contents from document headings
• Cross-References: Internal links between sections and documents
• SEO-Friendly: Semantic structure helps search engine indexing
• Theme Support: CSS classes on every element for easy custom styling
• Universal Rendering: Opens in every web browser on every platform

Practical Examples

Example 1: API Documentation Page

Input AsciiDoc file (api-reference.adoc):

= REST API Reference
:toc: left
:source-highlighter: highlight.js

== Authentication

All requests require an API key:

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

.Response Codes
|===
| Code | Description
| 200  | Success
| 401  | Unauthorized
| 404  | Not Found
|===

Output HTML file (api-reference.html):

Complete HTML documentation page:
✓ Sidebar table of contents with links
✓ Syntax-highlighted bash code block
✓ Styled responsive data table
✓ Semantic HTML5 structure (section, code)
✓ CSS classes for custom theming
✓ Ready to host on any web server
✓ Accessible with screen readers

Example 2: Project README for GitHub Pages

Input AsciiDoc file (index.adoc):

= MyProject
:icons: font
:sectanchors:

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

== Quick Start

. Clone the repository
. Run `npm install`
. Execute `npm start`

TIP: Use Node.js 18 or later for
best compatibility.

== Features

* Fast compilation
* Hot module reload
* TypeScript support

Output HTML file (index.html):

GitHub Pages ready:
✓ Image tag with alt text and dimensions
✓ Ordered list with inline code formatting
✓ Styled TIP admonition with icon
✓ Unordered feature list
✓ Section anchor links for deep linking
✓ Font Awesome icons integration
✓ Deployable directly to GitHub Pages

Example 3: Technical Article with Diagrams

Input AsciiDoc file (architecture.adoc):

= Microservices Architecture Guide
:toc:
:sectnums:

== Overview

The system uses three core services:

.Service Communication
[plantuml]
----
@startuml
UserService -> OrderService: createOrder
OrderService -> PaymentService: processPayment
@enduml
----

== Deployment

WARNING: Always deploy to staging first.

See <<monitoring>> for health checks.

[[monitoring]]
== Monitoring

Use `/health` endpoint for each service.

Output HTML file (architecture.html):

Professional documentation page:
✓ Numbered sections (1. Overview, 2. Deployment...)
✓ PlantUML diagram rendered as SVG/PNG
✓ WARNING admonition with styled callout
✓ Cross-reference link to Monitoring section
✓ Section anchors for bookmarking
✓ Complete HTML5 document structure
✓ Ready for documentation portal

Frequently Asked Questions (FAQ)

Q: Is the HTML output a full page or just a fragment?

A: By default, the conversion produces a complete HTML5 document with DOCTYPE, head (including title, meta charset, and stylesheet links), and body sections. If you need just the body content for embedding in an existing page or template system, Asciidoctor can also output an HTML fragment without the wrapping document structure.

Q: Does the HTML include CSS styling?

A: Yes. The generated HTML includes either an embedded stylesheet or a link to an external CSS file. Asciidoctor ships with a default theme that provides professional typography, responsive layout, styled admonitions, and code block formatting. You can customize the appearance by providing your own CSS file or modifying the default theme.

Q: How is source code highlighted in the HTML?

A: AsciiDoc source code blocks with language annotations are highlighted using libraries like highlight.js, Rouge, or Pygments. The HTML output contains pre/code elements with CSS classes for each token type (keywords, strings, comments), and the corresponding JavaScript or CSS provides the coloring. Over 100 programming languages are supported.

Q: Can I use the HTML output with a static site generator?

A: Absolutely. AsciiDoc integrates with Jekyll, Hugo, Antora, and many other static site generators. Antora is specifically designed for multi-repository AsciiDoc documentation sites. For Jekyll and Hugo, AsciiDoc plugins process .adoc files directly into the site's HTML pages with consistent navigation and layout.

Q: Are images and media preserved in HTML?

A: Yes. AsciiDoc image macros (image::file.png[]) become HTML img tags with proper alt text, dimensions, and optional figure/caption elements. The image files need to be available at the referenced paths relative to the HTML output. Videos and audio can also be embedded using AsciiDoc's video and audio macros.

Q: Is the generated HTML accessible?

A: Yes. Asciidoctor produces semantic HTML5 with proper heading hierarchy, alt text on images, ARIA landmarks, and logical document structure. This makes the output compatible with screen readers and other assistive technologies. The semantic markup also benefits SEO by helping search engines understand the document structure.

Q: Can I customize the HTML output?

A: Extensively. You can customize CSS styling, use custom HTML templates (Asciidoctor supports ERB/Slim/Haml templates), add custom JavaScript, include headers/footers, and modify virtually every aspect of the output. Document attributes in the AsciiDoc source control features like TOC placement, section numbering, and icon sets.

Q: How does AsciiDoc-to-HTML compare to Markdown-to-HTML?

A: AsciiDoc produces richer HTML output than Markdown because it supports more structural elements natively: admonitions, complex tables, source code callouts, cross-references, include directives, and conditional content. While Markdown is simpler for basic content, AsciiDoc's HTML output is better suited for technical documentation, books, and professional publications.