mkdocs-interwiki 🧭

DokuWiki-style InterWiki links for MkDocs — now with emoji icons!
Create shorthand cross-site links such as [[wp>Python|Wikipedia: Python]] or [[gh>mkdocs/mkdocs]], with configurable emojis like 🔗 or :interwiki-github:.

---

✨ Features

• ✅ DokuWiki-style syntax: [[prefix>target|Label]]
• ✅ Configurable link templates per prefix
• ✅ Optional emoji icons before or after each link
• ✅ Safe to use in Markdown tables (no | parsing conflicts)
• ✅ Per-page override of extra variables (via front matter)
• ✅ Works perfectly with MkDocs Material and pymdownx.emoji

---

🚀 Installation

pip install mkdocs-interwiki

Or from source:

git clone https://github.com/yourname/mkdocs-interwiki.git
cd mkdocs-interwiki
pip install -e .

---

⚙️ Configuration

In your mkdocs.yml:

plugins:
  - search
  - interwiki:
      maps:
        wp: "https://en.wikipedia.org/wiki/{target}"
        gh: "https://github.com/{target}"
        issue: "https://github.com/{repo}/issues/{target}"
      extra:
        repo: "myorg/myrepo"
      preprocess: true          # (default) prevent '|' from breaking tables
      emoji_default: "🔗"       # shown before every link unless overridden
      emoji_map:
        wp: "📘"
        gh: ":interwiki-github:"
        issue: "🐞"
      emoji_position: before    # before | after | none

---

🧩 Writing Links

Basic examples

See [[wp>Python|Wikipedia: Python]] and [[gh>mkdocs/mkdocs]].

Open issue [[issue>1234|Bug #1234]].

These render as:

📘 Wikipedia: Python :interwiki-github: mkdocs/mkdocs 🐞 Bug #1234

(Emoji rendering depends on configuration — see below.)

---

🎨 Emoji options

🔹 1. Default emoji

Set a single emoji_default to appear before every link.

emoji_default: "🔗"
emoji_position: before

🔹 2. Per-prefix emoji

Use emoji_map to assign emojis for specific prefixes.

emoji_map:
  wp: "📘"
  gh: ":interwiki-github:"    # uses pymdownx.emoji shortcode

🔹 3. Emoji position

Place the emoji before or after the link text:

emoji_position: after

Result: [Wikipedia: Python](...) 🔗

---

🧱 Using in tables

InterWiki links are automatically protected from Markdown’s table parser, so you can safely use them without escaping the | character:

| Name | Source |
|------|---------|
| Python | [[wp>Python|Wikipedia]] |
| MkDocs | [[gh>mkdocs/mkdocs|GitHub]] |

---

🧭 Per-page overrides

You can override variables (like {repo}) per page using front matter:

---
title: Custom Repo Page
interwiki_extra:
  repo: "other-org/other-repo"
---

Then [[issue>42]] → https://github.com/other-org/other-repo/issues/42.

---

💡 Tips for MkDocs Material users

If you want emoji shortcodes like :interwiki-github: to render as icons, enable pymdownx.emoji in your markdown_extensions:

markdown_extensions:
  - pymdownx.emoji:
      emoji_index: !!python/name:materialx.emoji.twemoji
      emoji_generator: !!python/name:materialx.emoji.to_svg

Otherwise, use Unicode emojis (🐙, 📘, etc.) which always display.

---

🧰 Developer notes

• maps defines {prefix}: {url-template} pairs; {target} is required.
• extra provides custom template variables ({repo}, {lang}, etc.).
• preprocess is enabled by default to protect against table parsing.
• The extension runs safely alongside other Markdown extensions.

---

🧪 Example preview

plugins:
  - interwiki:
      maps:
        gh: "https://github.com/{target}"
        wp: "https://en.wikipedia.org/wiki/{target}"
      emoji_default: "🔗"
      emoji_map:
        gh: ":interwiki-github:"
        wp: "📘"
      emoji_position: before

- [[gh>mkdocs/mkdocs|MkDocs repo]]
- [[wp>Python|Wikipedia: Python]]

Output (Material theme):

:interwiki-github: MkDocs repo 📘 Wikipedia: Python

---

🧾 License

MIT License © 2025 Your Name

---

🗓️ Changelog

0.1.3

• Added emoji support (default + per-prefix + position)
• Works with pymdownx.emoji or plain Unicode
• Improved safety inside Markdown tables

0.1.1

• Fixed “unbalanced parenthesis” regex issue
• Safer per-page variable overrides

0.1.0

• Initial release — DokuWiki-style InterWiki links

Changelog

0.1.1 — 2025-10-05

• Fix: regex compiled without VERBOSE caused “unbalanced parenthesis”
• Improve: safer per-page overrides via extension handle instead of re-registering

0.1.0 — 2025-10-05

• Initial public release with DokuWiki-like [[prefix>Target|Label]] links
• Configurable maps and extra variables
• Per-page interwiki_extra overrides
• URL-encoding of {target}