mkdocs-vwidalias

mkdocs-vwidalias is a tiny MkDocs plugin that generates root-level alias URLs based on a page’s front-matter ID.

• Front-matter:

  ---
  id: SV-OVERVIEW
  title: Services Overview
  ---

• Build output:

  site/SV-OVERVIEW.html

• When opened, it redirects to the canonical page (by default appending #SV-OVERVIEW):

  /path/to/page/#SV-OVERVIEW

Now you can share short links like:

https://yoursite/SV-OVERVIEW/

Features

• Reads a configurable front-matter field (id_field, default id)
• Emits alias pages at /<ID>.html (or /prefix/<ID>.html)
• Optional alias_prefix (e.g., /id/SV-OVERVIEW.html)
• Optional url_prefix (e.g., safe/ to produce safe/services/#ID)
• Optional #ID appended to the target (append_hash: true)
• Duplicate ID detection (warn or fail)
• Verbose logging for easy debugging

Install

pip install mkdocs-vwidalias

Configure (mkdocs.yml)

plugins:
  - search
  - vwidalias:
      id_field: "id"          # front-matter key
      alias_prefix: ""        # "" => /<ID>.html ; "id" => /id/<ID>.html
      url_prefix: ""          # prepend to redirect target (e.g., "safe/")
      append_hash: true       # append '#<ID>' to target URL
      fail_on_duplicate: false

Author pages

---
id: SV-OVERVIEW
title: Services Overview
---

# Services Overview
Hello!

Build the site and you’ll get:

• Alias: site/SV-OVERVIEW.html
• Redirect target: /services/overview/#SV-OVERVIEW (default) or safe/services/overview/#SV-OVERVIEW when url_prefix: "safe/"

Debugging

Run with verbose logs:

mkdocs build -v
# or
mkdocs serve -v

You should see:

[mkdocs_vwidalias] Aliases to emit: 1
[mkdocs_vwidalias] Emitted 1 alias pages. Prefix=''

Notes

• Keep id values unique across pages.
• Works best with MkDocs pretty URLs (default).
• Alias pages include a canonical link to the target for SEO.