Convert MediaWiki to AsciiDoc

Why Convert MediaWiki to AsciiDoc?

Converting MediaWiki markup to AsciiDoc format enables you to transform collaborative wiki content into professional, publication-ready documentation. While MediaWiki excels as a platform for community-driven content creation on sites like Wikipedia, AsciiDoc is purpose-built for authoring high-quality technical documents, books, and specifications that can be published in multiple formats simultaneously.

MediaWiki's markup language features distinctive syntax including == headings ==, '''bold''' and ''italic'' formatting, [[wiki links]], and complex constructs like templates and parser functions. These elements are powerful within the MediaWiki ecosystem but require a MediaWiki server for proper rendering. AsciiDoc provides equivalent or superior markup capabilities that work with standalone processing tools like Asciidoctor, eliminating the need for a server infrastructure.

One of AsciiDoc's greatest strengths is its multi-format output capability. From a single AsciiDoc source, you can generate HTML5, PDF, EPUB3, DocBook XML, man pages, and more. This makes it ideal for organizations that need to publish documentation in multiple formats -- something MediaWiki cannot do natively. AsciiDoc also supports advanced features like conditional content, document attributes, include directives with tag filtering, and admonition blocks that enhance technical writing.

The conversion from MediaWiki to AsciiDoc is particularly valuable for teams migrating from wiki-based documentation to docs-as-code workflows. AsciiDoc files integrate naturally with Git repositories, CI/CD pipelines, and modern documentation platforms like Antora. This enables versioned, branched, and reviewable documentation that follows the same development practices as your source code.

Key Benefits of Converting MediaWiki to AsciiDoc:

• Publication Quality: Generate professional PDF, EPUB, and HTML output from single source files
• Docs-as-Code: Integrate documentation into Git-based development workflows
• Modular Architecture: Build complex documents from reusable content fragments with includes
• Conditional Processing: Produce different output variants from the same source using attributes
• Server Independence: Process documents locally without needing a wiki server
• Code Excellence: Superior source code blocks with syntax highlighting and callouts
• CI/CD Integration: Automate documentation builds in continuous integration pipelines

Practical Examples

Example 1: Wiki Article Structure Conversion

Input MediaWiki file (guide.mediawiki):

= User Guide =

== Getting Started ==
Welcome to the '''User Guide'''. This document covers:

* [[Installation]]
* [[Configuration]]
* [[Usage]]

=== System Requirements ===
You need ''at least'' 4 GB of RAM.

{{Note|This guide is for version 3.0+}}

[[Category:Documentation]]
[[Category:User Guides]]

Output AsciiDoc file (guide.asciidoc):

= User Guide
:toc: left
:toclevels: 3
:keywords: Documentation, User Guides

== Getting Started
Welcome to the *User Guide*. This document covers:

* <<installation>>
* <<configuration>>
* <<usage>>

=== System Requirements
You need _at least_ 4 GB of RAM.

NOTE: This guide is for version 3.0+

Example 2: Wiki Table to AsciiDoc Table

Input MediaWiki file (comparison.mediawiki):

== Feature Comparison ==

{| class="wikitable sortable"
|-
! Feature !! Free Plan !! Pro Plan !! Enterprise
|-
| Storage || 5 GB || 100 GB || Unlimited
|-
| Users || 1 || 10 || Unlimited
|-
| Support || Community || Email || 24/7 Phone
|-
| API Access || {{No}} || {{Yes}} || {{Yes}}
|}

Output AsciiDoc file (comparison.asciidoc):

== Feature Comparison

[cols="1,1,1,1", options="header"]
|===
| Feature | Free Plan | Pro Plan | Enterprise

| Storage | 5 GB | 100 GB | Unlimited
| Users | 1 | 10 | Unlimited
| Support | Community | Email | 24/7 Phone
| API Access | No | Yes | Yes
|===

Example 3: Wiki Code and References to AsciiDoc

Input MediaWiki file (api_doc.mediawiki):

== API Reference ==

Use the getUser() method:

<syntaxhighlight lang="python">
response = api.getUser(id=42)
print(response.name)
</syntaxhighlight>

See also: [[API Authentication]]<ref>RFC 6749 - OAuth 2.0</ref>

{{Warning|Always validate input parameters}}

Output AsciiDoc file (api_doc.asciidoc):

== API Reference

Use the `getUser()` method:

[source,python]
----
response = api.getUser(id=42)
print(response.name)
----

See also: <<api-authentication>>footnote:[RFC 6749 - OAuth 2.0]

WARNING: Always validate input parameters

Frequently Asked Questions (FAQ)

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

A: Both .adoc and .asciidoc are valid extensions for AsciiDoc files. The .adoc extension is the recommended short form, while .asciidoc is the full-name extension. Both are processed identically by Asciidoctor. The .asc extension is also sometimes used but is less common. Choose whichever your team or project conventions prefer.

Q: How does MediaWiki's template system translate to AsciiDoc?

A: MediaWiki templates are converted to AsciiDoc equivalents based on their function. Information templates become document attributes, warning templates become admonition blocks (WARNING, NOTE, TIP), and content inclusion templates become AsciiDoc include directives. Complex templates with conditional logic may need manual adjustment since AsciiDoc uses a different approach to content reuse.

Q: Can AsciiDoc handle MediaWiki's interwiki links?

A: MediaWiki interwiki links like [[wikipedia:Article]] are converted to standard AsciiDoc URL links. AsciiDoc doesn't have a native interwiki system, but you can define link attributes in the document header to create reusable link prefixes. For example, defining :wikipedia: https://en.wikipedia.org/wiki/ allows you to write {wikipedia}Article as a shorthand.

Q: Will math formulas be preserved?

A: MediaWiki's <math> tags containing LaTeX formulas are converted to AsciiDoc's stem blocks. AsciiDoc supports mathematical notation through MathJax or KaTeX when the :stem: attribute is set. Inline math and display math are both supported. The LaTeX syntax itself remains unchanged; only the surrounding markup changes.

Q: How are MediaWiki image galleries handled?

A: MediaWiki gallery tags are converted to sequences of AsciiDoc image macros. AsciiDoc doesn't have a direct gallery equivalent, but images can be arranged using block layout features. Each image from the gallery becomes an individual image::filename[] macro with caption and sizing attributes. For grid layouts, you can use AsciiDoc's column features.

Q: Can I automate MediaWiki to AsciiDoc conversion for entire wikis?

A: Yes, for bulk conversion you can export MediaWiki pages using Special:Export, then process each page through our converter. Pandoc also supports batch conversion with scripting. For large wiki migrations, consider using the MediaWiki API to export pages programmatically and then convert them in batch. Maintain a mapping file for internal links between converted pages.

Q: Does AsciiDoc support MediaWiki's revision history?

A: MediaWiki's built-in revision history is a server-side feature that doesn't transfer to AsciiDoc files directly. However, AsciiDoc files stored in Git gain full version history, diff comparison, branching, and merge capabilities that are actually more powerful for document management. Many teams find Git-based versioning superior to wiki revision history for documentation projects.

Q: What is Antora and how does it relate to AsciiDoc?

A: Antora is a multi-repository documentation site generator built specifically for AsciiDoc content. It assembles documentation from multiple Git repositories and branches into a unified, navigable documentation site. After converting MediaWiki content to AsciiDoc, you can organize it into an Antora project for a professional documentation portal, replacing the wiki with a versioned documentation site.