Convert HTML to AsciiDoc

Why Convert HTML to AsciiDoc?

Converting HTML to AsciiDoc is valuable when you need to transform web content into clean, maintainable documentation. AsciiDoc's lightweight syntax makes it far easier to read and edit than HTML, while preserving the semantic structure of your content. This is especially useful when migrating documentation from wikis, blogs, or static websites into a docs-as-code workflow.

AsciiDoc is semantically equivalent to DocBook XML, meaning it can represent complex document structures including cross-references, admonitions, sidebars, and multi-part books. Unlike Markdown, AsciiDoc was designed from the ground up for technical documentation and supports features like include directives for modular content, conditional processing, and built-in table of contents generation without any plugins or extensions.

The docs-as-code approach, where documentation is treated like source code stored in version control, reviewed via pull requests, and built automatically, has become the industry standard for technical writing. AsciiDoc is one of the preferred formats for this workflow because its plain text nature works seamlessly with Git and other version control systems, while its rich feature set supports professional publishing output.

Tools like Asciidoctor can convert AsciiDoc back to HTML, PDF, EPUB, DocBook, and many other formats, making it a powerful intermediate format. By converting HTML to AsciiDoc, you gain a single source of truth that can be published to multiple output formats while remaining easy to maintain and update.

Key Benefits of Converting HTML to AsciiDoc:

• Readable Source: Clean, human-readable plain text instead of verbose HTML tags
• Docs-as-Code: Store documentation in Git alongside your source code
• Multi-Format Output: Generate HTML, PDF, EPUB, and more from a single source
• Technical Features: Admonitions, code blocks with syntax highlighting, cross-references
• Modular Content: Use include directives to organize large documentation sets
• Version Control: Plain text diffs make reviews and collaboration easy
• Professional Publishing: Produce print-quality output with Asciidoctor PDF

Practical Examples

Example 1: Web Documentation Page

Input HTML file (guide.html):

<h1>Installation Guide</h1>
<p>Follow these steps to install the application.</p>
<h2>Prerequisites</h2>
<ul>
  <li>Python 3.8 or later</li>
  <li>pip package manager</li>
</ul>
<h2>Steps</h2>
<pre><code>pip install myapp</code></pre>

Output AsciiDoc file (guide.adoc):

= Installation Guide

Follow these steps to install the application.

== Prerequisites

* Python 3.8 or later
* pip package manager

== Steps

 pip install myapp

Example 2: Blog Post Migration

Input HTML file (article.html):

<article>
  <h1>Best Practices for API Design</h1>
  <p>APIs should follow <strong>RESTful</strong>
  principles for consistency.</p>
  <blockquote>Good API design is not just
  about endpoints.</blockquote>
  <table>
    <tr><th>Method</th><th>Action</th></tr>
    <tr><td>GET</td><td>Read</td></tr>
    <tr><td>POST</td><td>Create</td></tr>
  </table>
</article>

Output AsciiDoc file (article.adoc):

= Best Practices for API Design

APIs should follow *RESTful* principles
for consistency.

____
Good API design is not just about endpoints.
____

|===
| Method | Action

| GET
| Read

| POST
| Create
|===

Example 3: Technical Reference Page

Input HTML file (reference.html):

<h1>Configuration Reference</h1>
<div class="warning">
  <p>Back up your config before editing.</p>
</div>
<h2>Database Settings</h2>
<dl>
  <dt>host</dt>
  <dd>The database hostname</dd>
  <dt>port</dt>
  <dd>The connection port (default: 5432)</dd>
</dl>

Output AsciiDoc file (reference.adoc):

= Configuration Reference

WARNING: Back up your config before editing.

== Database Settings

host::
The database hostname

port::
The connection port (default: 5432)

Frequently Asked Questions (FAQ)

Q: What is AsciiDoc?

A: AsciiDoc is a lightweight markup language for writing technical documentation, articles, and books. Created by Stuart Rackham in 2002, it uses simple plain text syntax that can be converted to HTML, PDF, EPUB, DocBook XML, and other formats. AsciiDoc is semantically equivalent to DocBook, making it powerful enough for professional publishing while remaining easy to read and write.

Q: How is AsciiDoc different from Markdown?

A: While both are lightweight markup languages, AsciiDoc offers significantly more features out of the box. AsciiDoc natively supports admonitions (NOTE, TIP, WARNING), include directives for modular content, cross-references, definition lists, sidebars, and complex tables. Markdown requires extensions or custom implementations for these features, and different Markdown flavors handle them inconsistently.

Q: Will all HTML elements be preserved in the conversion?

A: Most semantic HTML elements such as headings, paragraphs, lists, tables, links, images, code blocks, and blockquotes convert cleanly to AsciiDoc equivalents. However, purely presentational HTML elements, inline CSS styles, and JavaScript functionality do not have direct AsciiDoc counterparts and will either be simplified or omitted during conversion.

Q: Can I convert AsciiDoc back to HTML?

A: Yes! Converting AsciiDoc to HTML is one of its primary use cases. Asciidoctor, the main AsciiDoc processor, generates well-structured HTML5 output by default. You can also customize the output with templates and stylesheets. This round-trip capability makes AsciiDoc an excellent intermediate format for documentation workflows.

Q: What tools can I use to edit AsciiDoc files?

A: AsciiDoc files are plain text, so any text editor works. For the best experience, use VS Code with the AsciiDoc extension, IntelliJ IDEA with the AsciiDoc plugin, or Atom with asciidoc-preview. These editors provide syntax highlighting, live preview, and autocompletion. Online editors like AsciidocFX also offer a WYSIWYG-like experience.

Q: Is AsciiDoc suitable for large documentation projects?

A: AsciiDoc excels at large-scale documentation. Its include directive lets you split content across multiple files and assemble them into a single document. Tools like Antora provide a complete documentation site generator for multi-repository, multi-version documentation. Organizations like Red Hat, GitHub, and the Spring Framework use AsciiDoc for their documentation.

Q: What file extension does AsciiDoc use?

A: AsciiDoc files typically use the .adoc extension, which is the recommended convention by the Asciidoctor project. You may also encounter .asciidoc or .asc extensions in older projects. The .adoc extension is preferred because it is concise and widely recognized by editors, build tools, and platforms like GitHub and GitLab for rendering.

Q: Can AsciiDoc handle code syntax highlighting?

A: Yes, AsciiDoc has built-in support for source code blocks with syntax highlighting. You can specify the programming language for a code block and Asciidoctor will apply syntax highlighting using libraries like Rouge, Pygments, or highlight.js. This makes AsciiDoc particularly well-suited for technical documentation that includes code examples.