Convert Wiki to ADOC

Why Convert Wiki to ADOC?

Converting Wiki markup to AsciiDoc (ADOC) format is valuable when migrating collaborative wiki content into professional technical documentation. Wiki markup excels at online collaborative editing, but AsciiDoc provides a much richer feature set for structured technical writing, including admonitions, cross-references, conditional includes, and multi-format output capabilities that wiki markup simply cannot match.

AsciiDoc is specifically designed for technical documentation workflows, offering features like include directives for modular document assembly, source code highlighting with callouts, and the ability to generate HTML, PDF, EPUB, and DocBook output from a single source. These capabilities make it an ideal target format when wiki content needs to be transformed into polished, publishable documentation.

The conversion process maps wiki headings (== through ======) to AsciiDoc heading levels (== through ======), wiki bold ('''text''') to AsciiDoc bold (*text*), wiki italic (''text'') to AsciiDoc italic (_text_), and wiki links ([[target|label]]) to AsciiDoc cross-references or links. Tables, lists, and other structural elements are similarly translated to their AsciiDoc equivalents.

Organizations frequently convert wiki content to AsciiDoc when they need to produce user manuals, API documentation, or technical guides that require consistent formatting, version control integration, and professional output quality. AsciiDoc's compatibility with Git-based workflows makes it particularly attractive for software teams moving away from wiki-based documentation.

Key Benefits of Converting Wiki to ADOC:

• Professional Output: Generate polished PDF, HTML, and EPUB from a single source
• Modular Documents: Use include directives to assemble large documents from smaller files
• Technical Features: Admonitions, callouts, cross-references, and conditional content
• Version Control: Plain text format works perfectly with Git and other VCS tools
• Syntax Highlighting: Built-in support for code blocks with language-specific highlighting
• Toolchain Support: Asciidoctor ecosystem with extensions and integrations
• Publishing Pipeline: Automated document generation for CI/CD workflows

Practical Examples

Example 1: Headings and Text Formatting

Input Wiki file (article.wiki):

== Installation Guide ==
This section covers '''software installation'''.

=== Prerequisites ===
You need ''administrator access'' to proceed.

* Download the installer
* Run the setup wizard
* Follow the on-screen instructions

Output ADOC file (article.adoc):

== Installation Guide
This section covers *software installation*.

=== Prerequisites
You need _administrator access_ to proceed.

* Download the installer
* Run the setup wizard
* Follow the on-screen instructions

Example 2: Links and References

Input Wiki file (reference.wiki):

See [[Configuration Guide|the configuration page]] for details.

External resource: [https://example.com Example Website]

== Related Pages ==
* [[FAQ]]
* [[Troubleshooting]]
* [[Release Notes]]

Output ADOC file (reference.adoc):

See <<Configuration Guide,the configuration page>> for details.

External resource: https://example.com[Example Website]

== Related Pages
* <<FAQ>>
* <<Troubleshooting>>
* <<Release Notes>>

Example 3: Tables and Structured Content

Input Wiki file (data.wiki):

== System Requirements ==

{| class="wikitable"
|-
! Component !! Minimum !! Recommended
|-
| CPU || 2 GHz || 3 GHz
|-
| RAM || 4 GB || 8 GB
|-
| Disk || 20 GB || 50 GB
|}

Output ADOC file (data.adoc):

== System Requirements

[cols="1,1,1", options="header"]
|===
| Component | Minimum | Recommended

| CPU | 2 GHz | 3 GHz
| RAM | 4 GB | 8 GB
| Disk | 20 GB | 50 GB
|===

Frequently Asked Questions (FAQ)

Q: What is Wiki markup?

A: Wiki markup is the text formatting language used on wiki-based platforms like Wikipedia, Fandom, and DokuWiki. It uses intuitive symbols such as == for headings, '''bold''' for bold text, ''italic'' for italic text, and [[links]] for internal page links. Files typically use the .wiki or .mediawiki extension.

Q: What is AsciiDoc (ADOC)?

A: AsciiDoc is a lightweight markup language designed for writing technical documentation, books, and articles. It uses a clean, readable syntax and can be processed by Asciidoctor to generate HTML, PDF, EPUB, DocBook, and other output formats. ADOC files are plain text and work well with version control systems.

Q: Will wiki templates be converted?

A: Wiki templates (like infoboxes and navboxes) are platform-specific features that don't have a direct equivalent in AsciiDoc. The converter will extract the visible text content from templates. For complex template structures, you may need to manually restructure the content using AsciiDoc's include directives or custom attributes.

Q: Are wiki tables preserved in the conversion?

A: Yes, wiki tables using the {| ... |} syntax are converted to AsciiDoc table format using the |=== delimiters. Column headers, cell content, and basic table structure are preserved. Complex table styling may require manual adjustment in the resulting AsciiDoc file.

Q: Can I convert MediaWiki-specific syntax?

A: The converter handles standard MediaWiki markup including headings, text formatting, links, lists, tables, and basic templates. MediaWiki-specific extensions (like parser functions, Lua modules, or special tags) may not have direct AsciiDoc equivalents and will be converted as plain text where possible.

Q: How are wiki categories handled?

A: Wiki categories ([[Category:Name]]) are converted to AsciiDoc document attributes or metadata tags. Since AsciiDoc doesn't have a built-in category system, the categories are preserved as custom attributes at the top of the document that can be used by your documentation build system.

Q: What tools can I use to view ADOC files?

A: ADOC files can be viewed and rendered using Asciidoctor (Ruby or JavaScript), IDE extensions for VS Code and IntelliJ, GitHub and GitLab (native rendering), and various online AsciiDoc preview tools. You can also convert ADOC files to HTML or PDF using the Asciidoctor command-line tool.

Q: Is the conversion reversible?

A: While you can convert AsciiDoc back to Wiki markup, some AsciiDoc-specific features (like admonitions, include directives, and conditional content) don't have direct wiki equivalents. For best results, keep your original wiki files as a backup until you've verified the converted AsciiDoc content meets your needs.