mkdocs-ezlinks-plugin 0.1.2

A mkdocs plugin that makes linking to other documents easy.

mkdocs-ezlinks-plugin

Plugin for mkdocs which enables easier linking between pages.

This plugin was written in order to provide an up-to-date and feature complete plugin for easily referencing documents with a variety of features:

• File name linking (e.g. [Text](file))
• Absolute paths (e.g. [Text](/link/to/file.md))
• WikiLinks support (e.g. [[Link]])

Install

pip install mkdocs-ezlinks-plugin

Edit your mkdocs configuration file to enable the plugin:

plugins:
  - search
  - ezlinks

NOTE
If you have no plugins entry in your config file yet, you'll likely also want to add the search plugin. MkDocs enables it by default if there is no plugins entry set, but now you have to enable it explicitly.

Configuration Options

plugins:
    - search
    - ezlinks:
        - wikilinks: {true|false}
        - absolute: {true|false}

wikilinks

Determines whether to scan for wikilinks or not (See WikiLink Support).

absolute

Determines whether to translate absolute liks to relative links (see Absolute Links).

NOTE
This plugin does not function well when the 'wikilinks' markdown extension is enabled.

Features

Filename Links

Given a layout such as

- index.md
- folder/
  +-- filename.md
  +-- image.png

The following links will result in the following translations

Link	Translation
[Link Text](filename)	[Link Text](folder/filename.md)
[Link Text](filename#Anchor)	[Link Text](folder/filename.md#Anchor)
[Link Text](filename.md)	[Link Text](folder/filename.md)
[Link Text](filename.md#Anchor)	[Link Text](folder/filename.md#Anchor)
	
	

Absolute Links

Given a layout such as

- static/
  +-- image.png
- folder/
  +-- document.md
- index.md

Given that we are entering the links into the folder/document.md file,

Link	Translation
	

This behavior can be disabled by setting the absolute property to false in the mkdocs configuration file.

WikiLink Support

Given a layout such as

- folder1/
  +-- main.md
- folder2/
  +-- page-name.md
- images/
  +-- puppy.png

and these links are entered in folder1/main.md, this is how wikilinks will be translated

Link	Translation
[[Page Name]]	[Page Name](../folder2/page-name.md)
![[Puppy]]	
[[Page Name|Link Text]]	[Link Text](../folder2/page-name.md)
[[Page Name#Section Heading|Link Text]]	[Link Text](../folder2/page-name.md#section-heading)

Attribution

This work is highly inspired from the following plugins:

• mkdocs-autolinks-plugin
• mkdocs-roamlinks-plugin
• mkdocs-abs-rel-plugin

I have combined some the features of these plugins, fixed several existing bugs, and am adding features in order to provide a cohesive, up-to-date, and maintained solution for the mkdocs community.