Convert AsciiDoc to Wiki

Why Convert AsciiDoc to Wiki?

Converting AsciiDoc to MediaWiki markup is essential when you need to publish technical documentation on wiki platforms such as Wikipedia, Fandom, or corporate MediaWiki installations. While AsciiDoc excels at authoring comprehensive documentation offline, MediaWiki markup is the lingua franca of collaborative wikis, enabling teams and communities to edit and maintain content through web-based interfaces.

MediaWiki, the software behind Wikipedia, uses a specific markup syntax that differs significantly from AsciiDoc. Where AsciiDoc uses = for headings and * for bold, MediaWiki uses == == for headings and ''' for bold. Tables use completely different syntax: AsciiDoc's |=== delimiters become MediaWiki's {| |} notation. Internal links use [[double brackets]], and templates use {{double braces}}. Automated conversion handles these syntax differences, saving hours of manual reformatting.

The conversion process maps every AsciiDoc structural element to its MediaWiki equivalent. Headings are wrapped in equals signs on both sides. Bold and italic markers are converted to MediaWiki's apostrophe-based syntax. Tables are restructured using MediaWiki's pipe-based table syntax with proper header and row delimiters. Lists, links, and images are all translated to their wiki-native representations, producing output that renders correctly on any MediaWiki installation.

This conversion is particularly valuable for organizations that maintain both developer documentation (in AsciiDoc, version-controlled in Git) and user-facing knowledge bases (on MediaWiki). Rather than maintaining separate versions of the same content, teams can author in AsciiDoc and automatically publish to their wiki platform, ensuring consistency and reducing duplication of effort.

Key Benefits of Converting AsciiDoc to Wiki:

• Wikipedia Publishing: Create content ready for Wikipedia or sister projects
• Wiki Platform Support: Works with MediaWiki, Fandom, and similar platforms
• Collaborative Editing: Enable web-based editing by non-technical users
• Content Syndication: Publish documentation across wiki and non-wiki platforms
• Template Integration: Output works with MediaWiki templates and categories
• Version History: Wiki platforms provide built-in revision tracking
• Community Access: Lower barrier for community contributions

Practical Examples

Example 1: Software Documentation Page

Input AsciiDoc file (software-guide.adoc):

= DataSync Tool

== Overview

*DataSync* is an open-source data synchronization
utility supporting multiple databases.

== Supported Databases

* PostgreSQL 12+
* MySQL 8.0+
* SQLite 3.35+

== Configuration

.Database Connection Settings
|===
|Parameter |Default |Description

|host |localhost |Database server address
|port |5432 |Connection port
|timeout |30s |Connection timeout
|===

Output Wiki file (software-guide.wiki):

= DataSync Tool =

== Overview ==

'''DataSync''' is an open-source data synchronization
utility supporting multiple databases.

== Supported Databases ==

* PostgreSQL 12+
* MySQL 8.0+
* SQLite 3.35+

== Configuration ==

{| class="wikitable"
|+ Database Connection Settings
|-
! Parameter !! Default !! Description
|-
| host || localhost || Database server address
|-
| port || 5432 || Connection port
|-
| timeout || 30s || Connection timeout
|}

Example 2: Knowledge Base Article

Input AsciiDoc file (troubleshooting.adoc):

== Common Error Messages

=== Connection Refused

If you see the error `ECONNREFUSED`, check:

. Verify the service is running
. Check firewall rules
. Confirm the port is correct

See the xref:network-guide[Network Guide] for details.

NOTE: This error may also indicate DNS issues.

Output Wiki file (troubleshooting.wiki):

== Common Error Messages ==

=== Connection Refused ===

If you see the error ECONNREFUSED, check:

# Verify the service is running
# Check firewall rules
# Confirm the port is correct

See the [[Network Guide]] for details.

{{Note|This error may also indicate DNS issues.}}

Example 3: Product Comparison Article

Input AsciiDoc file (comparison.adoc):

== Framework Comparison

A side-by-side look at popular frameworks.

.Feature Matrix
|===
|Feature |React |Vue |Angular

|Learning Curve
|Moderate
|Easy
|Steep

|Performance
|Excellent
|Excellent
|Good

|Community
|Very Large
|Large
|Large
|===

For more details, visit https://example.com[our website].

Output Wiki file (comparison.wiki):

== Framework Comparison ==

A side-by-side look at popular frameworks.

{| class="wikitable"
|+ Feature Matrix
|-
! Feature !! React !! Vue !! Angular
|-
| Learning Curve || Moderate || Easy || Steep
|-
| Performance || Excellent || Excellent || Good
|-
| Community || Very Large || Large || Large
|}

For more details, visit [https://example.com our website].

Frequently Asked Questions (FAQ)

Q: What is MediaWiki markup?

A: MediaWiki markup (also called wikitext) is the markup language used by MediaWiki software, which powers Wikipedia, Wiktionary, Fandom, and thousands of other wiki websites. It uses a specific syntax for formatting: == for headings, ''' for bold, '' for italic, [[]] for internal links, and {| |} for tables. It is designed for collaborative web-based content editing.

Q: Can I use the converted content on Wikipedia?

A: Yes, the converted content uses standard MediaWiki markup that Wikipedia accepts. You can paste the output directly into Wikipedia's editor. However, remember that Wikipedia has strict content policies including notability, verifiability, and neutral point of view. Technical documentation may need to be adapted to meet Wikipedia's editorial guidelines before submission.

Q: How are AsciiDoc cross-references handled?

A: AsciiDoc cross-references (xref: syntax) are converted to MediaWiki internal links using [[double bracket]] notation. If the referenced target exists as a page in the wiki, the link will work automatically. External URLs are converted to MediaWiki's external link format using [single brackets with URL]. Anchor references within the same page use section linking syntax.

Q: Are AsciiDoc tables properly converted?

A: Yes, AsciiDoc tables are fully converted to MediaWiki table syntax. Header rows use the ! delimiter for header cells, regular rows use | for data cells, and the table is wrapped in {| and |} markers. The wikitable CSS class is applied for standard styling. Table captions from AsciiDoc become |+ caption lines in the wiki output.

Q: What happens to AsciiDoc admonitions?

A: AsciiDoc admonitions (NOTE, TIP, WARNING, IMPORTANT, CAUTION) are converted to MediaWiki template calls like {{Note|content}} or {{Warning|content}}. These templates must be defined on the target wiki for proper rendering. Most MediaWiki installations include standard notice templates, but you may need to create or adapt them for your specific wiki.

Q: Does the converter handle AsciiDoc include directives?

A: AsciiDoc include directives (include::file.adoc[]) are resolved during conversion if the referenced files are available. The included content is incorporated into the output and converted to wiki markup. If included files are not accessible, the include directive is noted as a comment. MediaWiki's own transclusion system ({{:PageName}}) serves a similar purpose.

Q: Can I edit the wiki output collaboratively?

A: That is one of the primary benefits of converting to wiki format. Once published on a MediaWiki installation, the content can be edited by anyone with appropriate permissions using the web-based editor. MediaWiki provides built-in revision history, diff views, talk pages for discussion, and watchlists for tracking changes to specific pages.

Q: Which wiki platforms support MediaWiki markup?

A: The output is compatible with any platform running MediaWiki software. This includes Wikipedia and all Wikimedia projects, Fandom (formerly Wikia), self-hosted MediaWiki installations, and services like Miraheze. Some other wiki engines also accept MediaWiki-compatible markup. Pandoc can further convert the wiki markup to other wiki formats if needed.