Convert Wiki to Markdown

Why Convert Wiki to Markdown?

Converting Wiki markup to Markdown is one of the most common documentation migration tasks. As organizations move from MediaWiki-based platforms to modern documentation systems like GitHub Pages, MkDocs, Docusaurus, or Obsidian, converting existing wiki content to Markdown becomes essential. Markdown has become the de facto standard for developer documentation and is natively supported by virtually every code hosting platform.

The syntactic differences between Wiki and Markdown are significant but systematic. Wiki headings use equal signs (== Heading ==) while Markdown uses hash symbols (## Heading). Bold text changes from triple apostrophes ('''bold''') to double asterisks (**bold**). Internal links shift from double brackets to standard Markdown link syntax. These predictable mappings enable reliable automated conversion.

Markdown offers several advantages over wiki markup for modern workflows. It integrates naturally with Git-based version control, renders beautifully on GitHub and GitLab, and works with dozens of static site generators. Unlike wiki markup, which requires a MediaWiki installation to render, Markdown files are immediately useful in any modern development environment.

One important consideration is that wiki templates and parser functions have no direct equivalent in Markdown. These dynamic features must be resolved or removed during conversion. However, for the vast majority of wiki content consisting of text, headings, lists, links, and tables, the conversion to Markdown produces clean, well-formatted output.

Key Benefits of Converting Wiki to Markdown:

• Platform Migration: Move wiki content to GitHub, GitLab, or Bitbucket seamlessly
• Modern Tooling: Leverage static site generators like Hugo, Jekyll, and MkDocs
• Version Control: Markdown works natively with Git for change tracking
• Developer Adoption: Markdown is the standard for technical documentation
• Readability: Markdown is cleaner and easier to read as source text
• Wide Support: Renders on hundreds of platforms without special software
• Note-Taking: Compatible with Obsidian, Notion, and other knowledge tools

Practical Examples

Example 1: Documentation Page Migration

Input Wiki file (setup.wiki):

== Getting Started ==

'''Prerequisites:'''
* Python 3.8 or higher
* pip package manager
* Git version control

=== Installation ===

# Clone the repository
# Run pip install -r requirements.txt
# Configure the [[Configuration|settings file]]

See also: [[FAQ]] | [[Troubleshooting]]

Output Markdown file (setup.markdown):

## Getting Started

**Prerequisites:**
- Python 3.8 or higher
- pip package manager
- Git version control

### Installation

1. Clone the repository
2. Run `pip install -r requirements.txt`
3. Configure the [settings file](Configuration.md)

See also: [FAQ](FAQ.md) | [Troubleshooting](Troubleshooting.md)

Example 2: Wiki Table to Markdown Table

Input Wiki file (comparison.wiki):

== Feature Comparison ==

{| class="wikitable sortable"
|-
! Feature !! Free Plan !! Pro Plan !! Enterprise
|-
| Storage || 5 GB || 50 GB || Unlimited
|-
| Users || 1 || 10 || Unlimited
|-
| Support || Community || Email || 24/7 Phone
|}

Output Markdown file (comparison.markdown):

## Feature Comparison

| Feature | Free Plan | Pro Plan | Enterprise |
|---------|-----------|----------|------------|
| Storage | 5 GB | 50 GB | Unlimited |
| Users | 1 | 10 | Unlimited |
| Support | Community | Email | 24/7 Phone |

Example 3: Formatted Content with Links

Input Wiki file (guide.wiki):

== API Reference ==

The API uses ''RESTful'' conventions. All endpoints return '''JSON'''.

=== Authentication ===

Use the Authorization header:
 Authorization: Bearer {{YOUR_TOKEN}}

For details, see [https://docs.example.com/auth API Auth Docs].

[[Category:API]] [[Category:Reference]]

Output Markdown file (guide.markdown):

## API Reference

The API uses *RESTful* conventions. All endpoints return **JSON**.

### Authentication

Use the `Authorization` header:
```
Authorization: Bearer YOUR_TOKEN
```

For details, see [API Auth Docs](https://docs.example.com/auth).

Frequently Asked Questions (FAQ)

Q: What is the difference between Wiki markup and Markdown?

A: Both are lightweight markup languages, but they use different syntax. Wiki uses equal signs for headings (== H2 ==), triple apostrophes for bold ('''bold'''), and double brackets for links ([[Link]]). Markdown uses hash symbols (## H2), double asterisks (**bold**), and bracket-parenthesis syntax ([Text](url)). Markdown is simpler and more widely adopted outside of wiki platforms.

Q: Will wiki templates be converted to Markdown?

A: Wiki templates (using double curly braces) do not have a direct equivalent in Markdown. During conversion, templates are either expanded to their content or represented as plain text. If your wiki relies heavily on templates, you may need to manually adjust some content after conversion.

Q: How are wiki categories handled?

A: Wiki categories ([[Category:Name]]) have no direct Markdown equivalent. During conversion, categories can be preserved as metadata in YAML front matter or listed at the end of the document. The specific handling depends on your target documentation system.

Q: Can I use the converted Markdown on GitHub?

A: Yes, the converted Markdown is fully compatible with GitHub-Flavored Markdown (GFM). It renders correctly in README files, wiki pages, issues, pull requests, and GitHub Pages. Tables, code blocks, and links are converted to GFM-compatible syntax.

Q: What happens to wiki internal links?

A: Internal wiki links ([[Page Name]]) are converted to standard Markdown links. The link target is preserved and can be adjusted to match your new documentation structure. Piped links ([[Page|Display Text]]) are converted to [Display Text](Page.md) format.

Q: Is the Markdown output compatible with static site generators?

A: Yes, the output works with all major static site generators including Hugo, Jekyll, MkDocs, Docusaurus, and Gatsby. You may need to add YAML front matter (title, date, tags) depending on your generator's requirements, but the body content is immediately usable.

Q: How are code blocks converted?

A: Wiki code blocks (using the <code>, <pre>, or <source> tags) are converted to Markdown fenced code blocks using triple backticks. If the wiki source specifies a programming language, that information is preserved for syntax highlighting.

Q: Can I convert an entire MediaWiki site to Markdown?

A: You can upload multiple wiki pages for batch conversion. For large-scale wiki exports, first export your wiki content using MediaWiki's Special:Export feature, then convert individual pages. This approach works well for migrating wiki documentation to GitHub repositories or static documentation sites.