Convert MediaWiki to ADOC

Why Convert MediaWiki to ADOC?

Converting MediaWiki markup to AsciiDoc (ADOC) format is essential when migrating wiki-based content to professional documentation systems. MediaWiki's markup language was designed for collaborative web editing on platforms like Wikipedia, but AsciiDoc excels at producing polished, multi-format output suitable for technical manuals, books, and specifications. By converting to ADOC, you unlock powerful publishing capabilities while preserving your content's structure and meaning.

MediaWiki markup uses distinctive syntax elements like == headings ==, '''bold''', ''italic'', [[internal links]], and complex table structures with {| and |}. While highly effective for wiki environments, this markup is tightly coupled to the MediaWiki rendering engine. AsciiDoc, by contrast, is a standalone markup language that can be processed by Asciidoctor to generate HTML, PDF, EPUB, DocBook, and many other formats without requiring a server-side wiki installation.

AsciiDoc offers advanced documentation features that MediaWiki lacks in standalone form, including conditional content inclusion, document attributes (variables), admonition blocks (NOTE, TIP, WARNING, CAUTION, IMPORTANT), source code highlighting with callouts, and modular document assembly through include directives. These features make ADOC particularly valuable for software documentation, API references, and technical specifications.

The conversion process maps MediaWiki headings to AsciiDoc section levels, transforms wiki-style formatting to AsciiDoc equivalents, and converts table markup to AsciiDoc's cleaner table syntax. Templates and transclusion become include directives, and links are reformatted appropriately. This creates clean, maintainable documentation files that integrate well with version control systems like Git and modern CI/CD documentation pipelines.

Key Benefits of Converting MediaWiki to ADOC:

• Multi-Format Publishing: Generate HTML, PDF, EPUB, and DocBook from a single source
• Professional Output: Produce polished technical documents and books
• Modular Documents: Use include directives for reusable content components
• Version Control Friendly: Plain text format works perfectly with Git workflows
• Conditional Content: Include or exclude sections based on attributes and output targets
• Code Documentation: Built-in syntax highlighting with callouts for code examples
• Offline Processing: No server required, process documents locally with Asciidoctor

Practical Examples

Example 1: Wiki Article to Technical Documentation

Input MediaWiki file (article.mediawiki):

== Installation Guide ==

'''MediaWiki''' requires the following:

* PHP 8.0 or later
* A supported database ([[MySQL]] or [[PostgreSQL]])
* Web server ([[Apache]] or [[Nginx]])

{| class="wikitable"
|-
! Component !! Minimum Version
|-
| PHP || 8.0
|-
| MySQL || 5.7
|}

Output ADOC file (article.adoc):

== Installation Guide

*MediaWiki* requires the following:

* PHP 8.0 or later
* A supported database (MySQL or PostgreSQL)
* Web server (Apache or Nginx)

|===
| Component | Minimum Version

| PHP
| 8.0

| MySQL
| 5.7
|===

Example 2: Wiki Template to AsciiDoc Attributes

Input MediaWiki file (template_page.mediawiki):

{{Infobox software
| name = MediaWiki
| developer = Wikimedia Foundation
| latest_version = 1.41
}}

== Overview ==
{{Main|MediaWiki overview}}

MediaWiki is ''free and open-source'' wiki software.
It was originally developed for [[Wikipedia]].

Output ADOC file (template_page.adoc):

:name: MediaWiki
:developer: Wikimedia Foundation
:latest_version: 1.41

== Overview

NOTE: See also MediaWiki overview

MediaWiki is _free and open-source_ wiki software.
It was originally developed for Wikipedia.

Example 3: Wiki References to AsciiDoc Footnotes

Input MediaWiki file (references.mediawiki):

== History ==

MediaWiki was created in 2002.<ref>Wikipedia history page</ref>

The software powers over 100,000 wikis.<ref>MediaWiki usage stats</ref>

=== Key milestones ===
* 2001: Wikipedia founded using UseModWiki
* 2002: '''Phase II''' software written by Magnus Manske
* 2003: '''Phase III''' (MediaWiki) deployed

== References ==
<references />

Output ADOC file (references.adoc):

== History

MediaWiki was created in 2002.footnote:[Wikipedia history page]

The software powers over 100,000 wikis.footnote:[MediaWiki usage stats]

=== Key milestones
* 2001: Wikipedia founded using UseModWiki
* 2002: *Phase II* software written by Magnus Manske
* 2003: *Phase III* (MediaWiki) deployed

[bibliography]
== References

Frequently Asked Questions (FAQ)

Q: What is MediaWiki markup?

A: MediaWiki markup is the wiki markup language used by Wikipedia and thousands of other wikis running MediaWiki software. Created in 2002, it uses syntax like == headings ==, '''bold''', ''italic'', [[links]], and special constructs for templates, tables, and categories. It is the most widely used wiki markup language in the world.

Q: What is AsciiDoc (ADOC)?

A: AsciiDoc is a lightweight markup language designed for writing technical documentation, articles, and books. Files use the .adoc extension and are processed by Asciidoctor to produce HTML, PDF, EPUB, DocBook, and other formats. It supports advanced features like includes, conditional content, admonitions, and source code highlighting.

Q: How are MediaWiki headings converted to AsciiDoc?

A: MediaWiki headings like == Heading == (with equals signs on both sides) are converted to AsciiDoc headings like == Heading (equals signs on the left side only). The heading levels map directly: == is level 2, === is level 3, and so on in both formats, making the conversion straightforward.

Q: What happens to MediaWiki templates during conversion?

A: MediaWiki templates are converted to the closest AsciiDoc equivalents. Simple templates may become AsciiDoc attributes or include directives. Infobox templates can be converted to structured content blocks. Complex templates with parser functions may require manual adjustment after conversion since AsciiDoc's template system differs fundamentally from MediaWiki's.

Q: Are MediaWiki tables preserved in AsciiDoc?

A: Yes, MediaWiki tables are converted to AsciiDoc table syntax. The {| ... |} table structure becomes AsciiDoc's |=== delimited block. Header rows, cell alignment, and spanning are mapped to their AsciiDoc equivalents. Complex table formatting like colored cells may need manual refinement.

Q: Can I convert MediaWiki categories and namespaces?

A: MediaWiki categories ([[Category:Name]]) are converted to AsciiDoc metadata or document attributes. Namespace prefixes are typically removed or converted to directory structures. Since AsciiDoc doesn't have a native category system, categories are usually represented as document attributes or tags that can be used by your documentation build system.

Q: What tools can process the resulting ADOC files?

A: Asciidoctor is the primary tool for processing ADOC files. It can generate HTML5, PDF (via asciidoctor-pdf), EPUB3 (via asciidoctor-epub3), and DocBook XML. Many IDEs and editors support ADOC preview, including VS Code, IntelliJ IDEA, and Atom. GitHub and GitLab render ADOC files natively in repositories.

Q: Is the conversion lossless?

A: The conversion preserves all text content, headings, formatting, links, lists, and basic table structures. However, some MediaWiki-specific features like parser functions, magic words, Lua module calls, and complex templates may not have direct AsciiDoc equivalents and will need manual review. The converter handles the most common markup elements accurately.