Skip to content

Markdown Link Prefix

A Python-Markdown extension that expands prefixed link shorthand into full URLs.

Markdown Link Prefix is a Python-Markdown extension. Write short links like Watch video or KB article; when rendered, they become normal URLs using templates you define in a YAML file or config. All prefixes come from link_prefixes.yaml (or prefixes_file) and/or the prefixes option—nothing is hard-coded. It works with Zensical, MkDocs, or any tool that uses Python-Markdown.

PyPI version Python 3.8+ License: MIT Deploy docs to GitHub Pages

Author: BarCar · Repository: github.com/barcar/markdown-link-prefix

BuyMeACoffee

Why use it?

  • Shorter, readable links in Markdown: [Watch](https://www.youtube.com/watch?v=VIDEO_ID) instead of long URLs.
  • Change URLs in one place: point all snkb: / snci: links to your ServiceNow instance by editing your link_prefixes.yaml or config—no search-and-replace in content.
  • Easy to add prefixes: define new ones (Jira, Confluence, internal tools) in config or a file.

Quick example

In your Markdown:

- [Watch video](youtube:dQw4w9WgXcQ)
- [KB article](snkb:KB0012345)

With the extension enabled and prefixes defined (in a YAML file or config), those render as normal links. All prefixes come from your link_prefixes.yaml (or prefixes_file) and/or the prefixes option—nothing is hard-coded. If the file is missing or empty and no config is given, no prefixes are defined.

Controlling prefixes without editing code

You can change or add prefixes in two ways—no code changes:

  1. Tool config (MkDocs, Zensical): in mkdocs.yml or zensical.toml, set the prefixes option (or use prefixes_file). Edit the config file when you want to add a prefix or change a URL template.

  2. External YAML file: set prefixes_file to a path (e.g. docs/link_prefixes.yaml). Edit that file whenever you want to add or change prefixes; the extension loads it at build time. Ideal for sharing one file across projects or non-developers.

See Configuration for details and examples.

Next steps

  • Demo – See YouTube link examples in action
  • Installation – Install and enable the extension
  • Configuration – Prefixes, prefixes_file, and all options
  • Usage – Zensical, MkDocs, and plain Python
  • Troubleshooting – Changelog 404, links not expanding, PyYAML