Convert DOCBOOK to MEDIAWIKI

Why Convert DocBook to MediaWiki?

Converting DocBook to MediaWiki bridges the gap between structured XML documentation and the world's most widely used wiki platform. MediaWiki powers Wikipedia, Wikimedia projects, and thousands of corporate and community wikis. By converting DocBook content to MediaWiki markup, you make authoritative technical documentation accessible to collaborative web-based editing and community contribution.

DocBook and MediaWiki both excel at structured content, but they serve fundamentally different purposes. DocBook is designed for author-driven, publish-once documentation with strict schema validation. MediaWiki is designed for collaborative, constantly-evolving content with built-in revision history. Converting from one to the other combines DocBook's content quality with MediaWiki's accessibility.

The conversion maps DocBook elements to their MediaWiki counterparts: <section><title> becomes == Heading ==, <itemizedlist> becomes * bullet lists, <table> becomes {| class="wikitable" |} syntax, and admonitions like <note> become {{Note|text}} template calls. Cross-references are converted to [[internal links]], and <ulink> elements become [external links].

Organizations maintaining documentation in DocBook -- such as Linux distributions, open-source projects, and enterprise software teams -- frequently need to publish content on internal or public wikis for broader access. This conversion automates the migration, enabling non-technical users to read, search, and contribute to the documentation through MediaWiki's familiar web interface.

Key Benefits of Converting DocBook to MediaWiki:

• Wiki Publishing: Publish DocBook content on Wikipedia-style wiki platforms
• Collaborative Editing: Enable community contributions through web-based 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
• Broader Access: Non-technical users can view and edit wiki content easily
• Search Integration: MediaWiki's built-in search indexes all content automatically

Practical Examples

Example 1: Technical Article to Wiki Page

Input DocBook file (protocol.xml):

<article xmlns="http://docbook.org/ns/docbook">
  <title>HTTP/2 Protocol Guide</title>
  <section>
    <title>Introduction</title>
    <para>HTTP/2 is a major revision of the
    HTTP network protocol.</para>
  </section>
  <section>
    <title>Key Features</title>
    <itemizedlist>
      <listitem><para>Multiplexing</para></listitem>
      <listitem><para>Header compression</para></listitem>
      <listitem><para>Server push</para></listitem>
    </itemizedlist>
    <note>
      <para>Requires TLS in most implementations.</para>
    </note>
  </section>
</article>

Output MediaWiki file (protocol.wiki):

= HTTP/2 Protocol Guide =

== Introduction ==

HTTP/2 is a major revision of the HTTP network protocol.

== Key Features ==

* Multiplexing
* Header compression
* Server push

{{Note|Requires TLS in most implementations.}}

[[Category:Network Protocols]]
[[Category:Web Standards]]

Example 2: Table and Code Block

Input DocBook file (reference.xml):

<section xmlns="http://docbook.org/ns/docbook">
  <title>Status Codes</title>
  <table>
    <tgroup cols="2">
      <thead><row>
        <entry>Code</entry>
        <entry>Meaning</entry>
      </row></thead>
      <tbody>
        <row><entry>200</entry>
        <entry>OK</entry></row>
        <row><entry>404</entry>
        <entry>Not Found</entry></row>
      </tbody>
    </tgroup>
  </table>
  <programlisting language="python">
import requests
r = requests.get("https://api.example.com")
print(r.status_code)</programlisting>
</section>

Output MediaWiki file (reference.wiki):

== Status Codes ==

{| class="wikitable"
! Code !! Meaning
|-
| 200 || OK
|-
| 404 || Not Found
|}


import requests
r = requests.get("https://api.example.com")
print(r.status_code)

Example 3: Warnings and Definitions

Input DocBook file (security.xml):

<section xmlns="http://docbook.org/ns/docbook">
  <title>Security Guidelines</title>
  <warning>
    <para>Never store passwords in plain text.</para>
  </warning>
  <variablelist>
    <varlistentry>
      <term>Encryption</term>
      <listitem><para>Use AES-256 for data at rest.</para></listitem>
    </varlistentry>
    <varlistentry>
      <term>Hashing</term>
      <listitem><para>Use bcrypt for passwords.</para></listitem>
    </varlistentry>
  </variablelist>
</section>

Output MediaWiki file (security.wiki):

== Security Guidelines ==

{{Warning|Never store passwords in plain text.}}

; Encryption
: Use AES-256 for data at rest.

; Hashing
: Use bcrypt for passwords.

[[Category:Security]]

Frequently Asked Questions (FAQ)

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. Open the page editor, switch to source editing mode (not VisualEditor), paste the content, preview it, and save. The MediaWiki engine will render it as formatted HTML.

Q: How are DocBook admonitions converted?

A: DocBook admonition elements (<note>, <warning>, <caution>, <tip>, <important>) are converted to MediaWiki template calls: {{Note|text}}, {{Warning|text}}, etc. These templates must exist on the target wiki. Most MediaWiki installations include these templates, but you may need to create them on a fresh wiki.

Q: How are DocBook cross-references handled?

A: DocBook <xref> elements and xml:id cross-references are converted to MediaWiki internal links using [[Page Name]] syntax. Section references become [[Page Name#Section]] links. External <ulink> elements become [URL display text] external links.

Q: Do DocBook tables convert properly to MediaWiki?

A: Yes. MediaWiki has a powerful table system that supports the full complexity of DocBook tables. The conversion maps DocBook <table> elements to MediaWiki {| class="wikitable" syntax, preserving headers (! cells), data rows (| cells), and row separators (|-). Complex spanning is handled with colspan and rowspan attributes.

Q: What happens to DocBook code listings?

A: DocBook <programlisting> elements are converted to MediaWiki <syntaxhighlight lang="..."> tags, which provide syntax highlighting through the SyntaxHighlight extension. This extension is installed by default on Wikipedia and most MediaWiki installations. Inline code (<code>) is wrapped in <code> tags.

Q: Are categories automatically added?

A: The converter can add [[Category:...]] tags based on the DocBook document's subject matter and metadata. You can customize the categories after conversion. Categories are a key organizational feature of MediaWiki that helps users discover related content.

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 instances. It is the standard markup for all MediaWiki-based platforms.

Q: Can I convert MediaWiki back to DocBook?

A: Yes, reverse conversion is possible through our converter. However, MediaWiki-specific features like templates ({{template}}), categories, transclusion, and parser functions have no direct DocBook equivalents and would need manual adaptation. Basic content structure converts cleanly in both directions.