Convert AsciiDoc to MediaWiki

Why Convert AsciiDoc to MediaWiki?

Converting AsciiDoc documents to MediaWiki format is the bridge between author-driven technical documentation and collaborative wiki-based knowledge systems. MediaWiki powers Wikipedia, the world's largest encyclopedia, along with thousands of corporate wikis, community knowledge bases, and project documentation portals. When your well-structured AsciiDoc content needs to reach a wiki audience, this conversion makes it possible.

MediaWiki markup has its own distinctive syntax that differs significantly from AsciiDoc. Headings use paired equals signs (== Heading ==), links use double brackets ([[Page Name]]), and tables use a pipe-based syntax with {| and |} delimiters. The conversion process maps AsciiDoc's semantic elements to their MediaWiki counterparts: admonition blocks become template calls like {{Note|text}}, cross-references become internal wiki links, and code blocks are wrapped in <syntaxhighlight> tags or <code> elements.

One of the most valuable aspects of MediaWiki format is its template system, which allows reusable content blocks called through transclusion. While AsciiDoc uses include directives for document composition, MediaWiki templates serve a similar purpose in a wiki context. Converting to MediaWiki format positions your content for integration with existing wiki templates, infoboxes, and navigation structures that the wiki community has already built.

Organizations frequently maintain technical documentation in AsciiDoc within Git repositories and need to publish portions of that content on internal wikis for broader access. The conversion handles the syntax transformation while preserving the document's logical structure, enabling non-technical staff to access and contribute to the knowledge base through MediaWiki's web-based editing interface.

Key Benefits of Converting AsciiDoc to MediaWiki:

• Wiki Publishing: Publish AsciiDoc content on Wikipedia-style wiki platforms
• Collaborative Editing: Enable community contributions through web-based wiki editing
• Template Integration: Leverage existing wiki templates, infoboxes, and navigation
• Category Organization: Structure content with MediaWiki categories and namespaces
• Version Tracking: Built-in revision history and change tracking in the wiki
• Broader Access: Non-technical users can view and edit wiki content easily
• Knowledge Base: Build searchable corporate or community knowledge bases

Practical Examples

Example 1: Technical Article Migration

Input AsciiDoc file (article.adoc):

= REST API Design Principles
:author: Documentation Team

== Introduction

REST (Representational State Transfer) is
an architectural style for web services.

=== Key Principles

* Statelessness
* Client-server separation
* Uniform interface

NOTE: These principles were defined
by Roy Fielding in his 2000 dissertation.

Output MediaWiki file (article.wiki):

= REST API Design Principles =

== Introduction ==

REST (Representational State Transfer) is
an architectural style for web services.

=== Key Principles ===

* Statelessness
* Client-server separation
* Uniform interface

{{Note|These principles were defined
by Roy Fielding in his 2000 dissertation.}}

[[Category:API Design]]

Example 2: Product Documentation with Tables

Input AsciiDoc file (specs.adoc):

== Hardware Specifications

|===
| Component | Specification

| Processor
| ARM Cortex-A72, 1.8 GHz

| Memory
| 8 GB DDR4

| Storage
| 256 GB NVMe SSD
|===

See also: xref:software-specs[Software Specs]

Output MediaWiki file (specs.wiki):

== Hardware Specifications ==

{| class="wikitable"
! Component !! Specification
|-
| Processor || ARM Cortex-A72, 1.8 GHz
|-
| Memory || 8 GB DDR4
|-
| Storage || 256 GB NVMe SSD
|}

See also: [[Software Specs]]

Example 3: Code Documentation for Wiki

Input AsciiDoc file (setup.adoc):

== Development Setup

WARNING: Requires admin privileges.

[source,bash]
----
git clone https://repo.example.com/project
cd project
./configure --prefix=/usr/local
make && sudo make install
----

TIP: Use `--with-debug` flag for
development builds.

Output MediaWiki file (setup.wiki):

== Development Setup ==

{{Warning|Requires admin privileges.}}


git clone https://repo.example.com/project
cd project
./configure --prefix=/usr/local
make && sudo make install


{{Tip|Use --with-debug flag
for development builds.}}

Frequently Asked Questions (FAQ)

Q: What is MediaWiki markup?

A: MediaWiki markup (also called wikitext) is the formatting language used by MediaWiki software, which powers Wikipedia and thousands of other wikis. It uses distinctive syntax like == headings ==, [[internal links]], '''bold''', ''italic'', and {| table |} markers to format content that is rendered as HTML by the MediaWiki engine.

Q: Can I paste the converted text directly into a wiki?

A: Yes. The converted MediaWiki markup can be pasted directly into the source editor of any MediaWiki-based wiki. Simply open the page editor, switch to source editing mode (not visual editor), paste the converted content, preview it, and save. The wiki engine will render it as formatted HTML.

Q: How are AsciiDoc admonitions converted to MediaWiki?

A: AsciiDoc admonition blocks (NOTE, TIP, WARNING, CAUTION, IMPORTANT) are converted to MediaWiki template calls such as {{Note|text}}, {{Tip|text}}, and {{Warning|text}}. These templates must exist on the target wiki. Most MediaWiki installations have these templates available, but you may need to create them on a fresh wiki.

Q: Do AsciiDoc tables convert well to MediaWiki tables?

A: Yes. MediaWiki has a powerful table system that supports the full complexity of AsciiDoc tables, including column headers, row separators, and styling. The conversion maps AsciiDoc table syntax to MediaWiki's {| class="wikitable" format, preserving the table structure and content accurately.

Q: What happens to source code blocks?

A: AsciiDoc source code blocks with language identifiers are converted to MediaWiki <syntaxhighlight lang="..."> tags, which provide syntax highlighting through the SyntaxHighlight extension (installed by default on Wikipedia and most wikis). Inline code is wrapped in <code> tags.

Q: Are cross-references converted to wiki links?

A: AsciiDoc cross-references (xref and <<anchor>>) are converted to MediaWiki internal links ([[Page Name]]) where possible. Section references become links with anchors ([[Page Name#Section]]). Note that the target wiki pages must exist for the links to work properly.

Q: Can I convert MediaWiki back to AsciiDoc?

A: Yes, reverse conversion is possible through our converter. However, MediaWiki-specific features like templates, categories, transclusion, and parser functions have no direct AsciiDoc equivalents and would need manual adaptation. The basic content structure (headings, lists, tables, text) converts cleanly in both directions.

Q: Which wikis support the converted output?

A: The converted MediaWiki markup works with any MediaWiki-powered wiki, including Wikipedia, Wikimedia Commons, Wiktionary, Fandom wikis (formerly Wikia), corporate MediaWiki installations, and self-hosted MediaWiki instances. It is the standard markup for all MediaWiki-based platforms.