Convert Wiki to AsciiDoc

Why Convert Wiki to AsciiDoc?

Converting Wiki markup to AsciiDoc is an essential step when transitioning from wiki-based content management to professional documentation workflows. While wiki platforms excel at collaborative editing, AsciiDoc provides the structural sophistication needed for producing high-quality technical documentation, user manuals, and publishable content in multiple output formats.

AsciiDoc surpasses wiki markup in almost every documentation capability. It supports conditional content inclusion, document assembly through include directives, admonition blocks for callouts, source code listing with syntax highlighting and callout markers, and sophisticated cross-referencing. These features make it the preferred choice for organizations that need to maintain comprehensive, version-controlled documentation.

The migration from wiki to AsciiDoc is particularly common in software development organizations that want to keep their documentation alongside their code in Git repositories. AsciiDoc's plain-text nature makes it ideal for diff-based code review, branching, and merging -- workflows that wiki platforms handle poorly. The Asciidoctor toolchain can then generate HTML sites, PDF manuals, and EPUB ebooks from the same source files.

During conversion, wiki-specific elements like templates, categories, and interwiki links are mapped to AsciiDoc equivalents where possible, or preserved as comments for manual review. The resulting AsciiDoc files are clean, maintainable, and ready for integration into modern documentation build systems like Antora, Jekyll-asciidoc, or custom CI/CD pipelines.

Key Benefits of Converting Wiki to AsciiDoc:

• Multi-Format Publishing: Generate HTML, PDF, EPUB, DocBook, and man pages from one source
• Document Modularity: Split large documents into includable parts for easier maintenance
• Git-Friendly: Plain text format integrates perfectly with version control workflows
• Admonitions: Built-in support for NOTE, TIP, WARNING, CAUTION, and IMPORTANT blocks
• Code Documentation: Syntax-highlighted code blocks with inline callout annotations
• Conditional Processing: Include or exclude content based on attributes and build targets
• Professional Quality: Publication-grade output for books, manuals, and specifications

Practical Examples

Example 1: Document Structure and Formatting

Input Wiki file (guide.wiki):

= Main Title =
== Getting Started ==
This guide explains '''how to install''' the software.

=== System Requirements ===
* ''Operating System'': Windows 10 or later
* '''RAM''': 8 GB minimum
* Disk space: 500 MB

=== Download ===
Visit [https://example.com/download the download page].

Output AsciiDoc file (guide.asciidoc):

= Main Title
== Getting Started
This guide explains *how to install* the software.

=== System Requirements
* _Operating System_: Windows 10 or later
* *RAM*: 8 GB minimum
* Disk space: 500 MB

=== Download
Visit https://example.com/download[the download page].

Example 2: Complex Lists and Nested Content

Input Wiki file (procedures.wiki):

== Deployment Steps ==

# Prepare the environment
## Install dependencies
## Configure settings
# Build the application
#* Run unit tests
#* Run integration tests
# Deploy to staging
# Verify deployment

{{Note|Always back up before deploying.}}

Output AsciiDoc file (procedures.asciidoc):

== Deployment Steps

. Prepare the environment
.. Install dependencies
.. Configure settings
. Build the application
* Run unit tests
* Run integration tests
. Deploy to staging
. Verify deployment

NOTE: Always back up before deploying.

Example 3: Tables and Code Blocks

Input Wiki file (api.wiki):

== API Endpoints ==

{| class="wikitable"
|-
! Method !! Endpoint !! Description
|-
| GET || /api/users || List all users
|-
| POST || /api/users || Create a user
|-
| DELETE || /api/users/:id || Delete a user
|}


{
  "name": "John",
  "email": "[email protected]"
}

Output AsciiDoc file (api.asciidoc):

[source,json]
== API Endpoints

[cols="1,2,3", options="header"]
|===
| Method | Endpoint | Description

| GET | /api/users | List all users
| POST | /api/users | Create a user
| DELETE | /api/users/:id | Delete a user
|===

[source,json]
----
{
  "name": "John",
  "email": "[email protected]"
}
----

Frequently Asked Questions (FAQ)

Q: What is the difference between ADOC and AsciiDoc extensions?

A: Both .adoc and .asciidoc are valid file extensions for AsciiDoc documents. The .adoc extension is shorter and more commonly used in modern projects, while .asciidoc is the original full-length extension. Both are processed identically by Asciidoctor and other AsciiDoc tools. The content and syntax are exactly the same regardless of which extension you use.

Q: How does AsciiDoc compare to Markdown?

A: AsciiDoc is more powerful than Markdown, offering built-in support for admonitions, includes, cross-references, conditional content, footnotes, and complex tables without needing extensions. Markdown is simpler and more widely adopted for basic content, while AsciiDoc excels at technical documentation that requires rich formatting and multi-format output.

Q: Will wiki interwiki links be preserved?

A: Interwiki links (like [[wikipedia:Article]]) are converted to standard AsciiDoc URL links where the target URL can be resolved. Links to other wiki pages within the same wiki are converted to AsciiDoc cross-references. Any links that cannot be automatically resolved are preserved as comments for manual review.

Q: Can I convert an entire wiki to AsciiDoc?

A: Yes, you can export individual wiki pages as .wiki files and convert them one at a time or in batch. For large wiki sites, you may want to export using the Special:Export feature of MediaWiki to get XML dumps, then use tools like pandoc to perform bulk conversion. Our converter handles individual .wiki files efficiently.

Q: How are wiki images handled in the conversion?

A: Wiki image references ([[File:image.png|caption]]) are converted to AsciiDoc image macros (image::image.png[caption]). The actual image files need to be exported separately from the wiki and placed in the appropriate directory. The converter updates all image references to use AsciiDoc syntax.

Q: Does AsciiDoc support wiki-style categories?

A: AsciiDoc doesn't have a built-in category system like MediaWiki. Categories are converted to document attributes (e.g., :categories: Category1, Category2) that can be used by documentation site generators like Antora to organize and classify content. You can also use tags in your build system to replicate category functionality.

Q: What tools process AsciiDoc files?

A: The primary tool is Asciidoctor, available in Ruby, JavaScript (asciidoctor.js), and Java. It generates HTML5, PDF (via asciidoctor-pdf), EPUB3, and DocBook XML. Pandoc also supports AsciiDoc. IDEs like VS Code and IntelliJ have AsciiDoc preview extensions. GitHub and GitLab render AsciiDoc files natively.

Q: Can I use AsciiDoc for a documentation website?

A: Yes, Antora is a purpose-built documentation site generator for AsciiDoc content. It supports multi-repository, multi-version documentation sites with navigation, search, and customizable themes. You can also use Jekyll with the jekyll-asciidoc plugin, or generate static HTML directly with Asciidoctor and host it on any web server.