/autolink-references-mkdocs-plugin

Provides GitHub like autolink references in Mkdocs.

Primary LanguagePythonMIT LicenseMIT

Autolink References (MkDocs Plugin)

This mkdocs plugin look in each MkDocs article for the presence of a reference to tickets from issues trackers like Jira, Linear, etc and convert them to links that point to respective platforms:

Getting started

To install it, using pip:

pip install autolink-references-mkdocs-plugin

Edit your mkdocs.yml file and add these few lines of code:

plugins:
   - autolink_references:
        autolinks:
            - reference_prefix: AF-
              target_url: https://linear.com/AF-<num>
            - reference_prefix: PROJ-
              target_url: https://jiracloud.com/PROJ-<num>
            - reference_prefix: GIT@
              target_url: https://github.com/<num>
              look_for_alphanumeric_id: true
  • reference_prefix: This prefix appended by a number will generate a link any time it is found in a page.
  • target_url: The URL must contain <num> for the reference number.
  • look_for_alphanumeric_id: (optional, default=false) Allow values for <num> that are not only numeric but also alphanumeric including "-_/"

An example

For example, you could edit the docs/index.md file and insert the ticket references like this:

Changelog:

- AF-100: add new feature.

This will generate pre-processed to:

Changelog:

- [AF-100](https://linear.com/AF-100): add new feature.

Changelog

0.2.0

  • Ignore already linked references.
  • Converts text [AF-100] to a linked version and removes the brackets AF-100

License

MIT

Built with ❤️ by Saurabh Kumar