Convert ADOC to MediaWiki

Why Convert ADOC to MediaWiki?

Converting AsciiDoc to MediaWiki format enables you to migrate technical documentation into collaborative wiki environments. MediaWiki, the software powering Wikipedia and thousands of corporate wikis, provides a proven platform for knowledge management and community-driven content.

MediaWiki markup is specifically designed for collaborative editing with features like version history, diff comparison, rollback capabilities, and user permissions. By converting your AsciiDoc documentation to MediaWiki format, you make it accessible to a broader audience who can contribute improvements, corrections, and additions.

The MediaWiki platform excels at organizing large amounts of interconnected content through categories, namespaces, and automatic cross-linking. Wikipedia's success demonstrates the scalability of this approach—the same software can power your organization's internal knowledge base with enterprise-grade features.

This conversion is ideal when you need to transition from author-centric documentation to community-editable wiki content, migrate technical docs to corporate wikis, or publish reference material that benefits from collaborative maintenance.

Key Benefits of Converting ADOC to MediaWiki:

• Wikipedia Collaboration: Enable collaborative editing with built-in version history and diff tracking
• Knowledge Base Creation: Migrate docs to corporate wikis for internal knowledge sharing
• Template Integration: Leverage MediaWiki's powerful template system for consistent formatting
• Category Organization: Organize content into navigable hierarchies users can browse
• Cross-Linking: Automatic internal linking enhances content discoverability
• Version Control: Every edit tracked with full history and rollback capabilities
• Search Integration: Content instantly searchable across your wiki installation

Practical Examples

Example 1: Technical Documentation Page

Input ADOC file (python.adoc):

= Python Programming Language
:author: Documentation Team

== Overview

Python is a high-level, interpreted programming language
known for its clear syntax and readability.

== Features

* Dynamic typing
* Automatic memory management
* Large standard library
* Cross-platform compatibility

== Code Example

[source,python]
----
def hello_world():
    print("Hello, World!")
----

== See Also

* link:java.html[Java Programming]
* link:javascript.html[JavaScript]

Output MediaWiki file (Python.wiki):

= Python Programming Language =

== Overview ==

Python is a high-level, interpreted programming language
known for its clear syntax and readability.

== Features ==

* Dynamic typing
* Automatic memory management
* Large standard library
* Cross-platform compatibility

== Code Example ==

<syntaxhighlight lang="python">
def hello_world():
    print("Hello, World!")
</syntaxhighlight>

== See Also ==

* [[Java Programming]]
* [[JavaScript]]

[[Category:Programming Languages]]

Example 2: Reference Documentation with Tables

Input ADOC file (http-codes.adoc):

= HTTP Status Codes Reference

== Success Responses (2xx)

|===
| Code | Name | Description

| 200
| OK
| Request succeeded

| 201
| Created
| Resource created successfully

| 204
| No Content
| Success with no response body
|===

NOTE: Always check the response body for details.

Output MediaWiki file (HTTP_Status_Codes.wiki):

= HTTP Status Codes Reference =

== Success Responses (2xx) ==

{| class="wikitable"
|-
! Code !! Name !! Description
|-
| 200 || OK || Request succeeded
|-
| 201 || Created || Resource created successfully
|-
| 204 || No Content || Success with no response body
|}

{{Note|Always check the response body for details.}}

[[Category:HTTP]]
[[Category:Web Development]]

Example 3: Tutorial with Installation Steps

Input ADOC file (git-setup.adoc):

= Setting Up Git

== Prerequisites

. A computer running Windows, macOS, or Linux
. Administrator access
. Internet connection

== Installation

Download Git from https://git-scm.com[git-scm.com].

== Configuration

[source,bash]
----
git config --global user.name "Your Name"
git config --global user.email "[email protected]"
----

TIP: Use SSH keys for secure authentication.

Output MediaWiki file (Git_Setup.wiki):

= Setting Up Git =

== Prerequisites ==

# A computer running Windows, macOS, or Linux
# Administrator access
# Internet connection

== Installation ==

Download Git from [https://git-scm.com git-scm.com].

== Configuration ==

<syntaxhighlight lang="bash">
git config --global user.name "Your Name"
git config --global user.email "[email protected]"
</syntaxhighlight>

{{Tip|Use SSH keys for secure authentication.}}

[[Category:Tutorials]]
[[Category:Version Control]]

Frequently Asked Questions (FAQ)

Q: Can I paste the converted content directly into Wikipedia?

A: Yes! The MediaWiki markup produced is compatible with Wikipedia and all MediaWiki installations. However, Wikipedia has specific content guidelines, notability requirements, and neutral point of view policies that your content must meet for publication.

Q: How are AsciiDoc code blocks converted for MediaWiki?

A: Code blocks are converted to MediaWiki's <syntaxhighlight> tags which provide syntax highlighting when the SyntaxHighlight extension is installed (standard on Wikipedia). The language specification is preserved for proper highlighting.

Q: What happens to AsciiDoc admonitions like NOTE and TIP?

A: Admonitions are converted to MediaWiki template calls like {{Note}} and {{Tip}}. These templates must exist on your target wiki; most wikis have equivalent templates, or you can easily create them.

Q: Are internal links preserved during conversion?

A: Yes! Internal links are converted to MediaWiki's double-bracket link format [[Page Name]]. You may need to adjust page names to match your wiki's naming conventions (spaces vs underscores, capitalization) after conversion.

Q: How are images handled in the conversion?

A: Image references are converted to MediaWiki's [[File:name.ext]] syntax. The actual image files must be uploaded separately to your MediaWiki installation's file repository before they will display.

Q: Can I convert tables with complex formatting?

A: Tables are converted to MediaWiki's wikitable format with proper headers and cells. Complex features like column spans and row spans are converted where MediaWiki supports them using colspan and rowspan attributes.

Q: Will categories be added to my converted content?

A: The converter can suggest categories based on document attributes and content. You should add or modify [[Category:Name]] tags after conversion to match your wiki's category structure and naming conventions.

Q: Is the converted markup compatible with Semantic MediaWiki?

A: Yes! The basic MediaWiki markup is fully compatible with Semantic MediaWiki installations. You can add semantic properties like [[Property::Value]] and annotations after conversion to leverage Semantic MediaWiki's advanced features.