Skip to main content
Join the official 2019 Python Developers SurveyStart the survey!

A MkDocs plugin for dynamic page redirects to prevent broken links.

Project description

mkdocs-redirects

Plugin for mkdocs to create page redirects (e.g. for moved/renamed pages).

Installing

Note: This package requires MkDocs version 1.0.4 or higher.

Install with pip:

pip install mkdocs-redirects

Using

To use this plugin, specify your desired redirects in the plugin's redirect_maps setting in your mkdocs.yml:

plugins:
    - redirects:
        redirect_maps:
            'old.md': 'new.md'
            'old/file.md': 'new/file.md'
            'some_file.md': 'http://external.url.com/foobar'

Note: don't forget that specifying the plugins setting will override the defaults if you didn't already have it set! See this page for more information.

The redirects map should take the form of a key/value pair:

  • The key of each redirect is the original markdown doc (relative to the docs_dir path).
    • This plugin will handle the filename resolution during the mkdocs build process. This should be set to what the original markdown doc's filename was (or what it would be if it existed), not the final HTML file rendered by MkDocs
  • The value is the redirect target. This can take the following forms:
    • Path of the markdown doc you wish to be redirected to (relative to docs_dir)
      • This plugin will handle the filename resolution during the mkdocs build process. This should be set to what the markdown doc's filename is, not the final HTML file rendered by MkDocs
    • External URL (e.g. http://example.com)

During the mkdocs build process, this plugin will create .html files in site_dir for each of the "old" file that redirects to the "new" path. It will produce a warning if any problems are encountered or of the redirect target doesn't actually exist (useful if you have strict: true set).

use_directory_urls

If you have use_directory_urls: true set (which is the default), this plugin will modify the redirect targets to the directory URL, not the actual index.html filename. However, it will create the index.html file for each target in the correct place so URL resolution works.

For example, a redirect map of 'old/dir/README.md': 'new/dir/README.md' will result in an HTML file created at $site_dir/old/dir/index.html which redirects to `/new/dir/.

Additionally, a redirect map of 'old/dir/doc_name.md': 'new/dir/doc_name.md' will result in $site_dir/old/dir/doc_name/index.html redirecting to /new/dir/doc_name/

This mimcs the behavior of how MkDocs builds the site dir without this plugin.

Contributing

Releasing

make release

It will prompt you for your PyPI user and password.

See:

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for mkdocs-redirects, version 1.0.0
Filename, size File type Python version Upload date Hashes
Filename, size mkdocs-redirects-1.0.0.tar.gz (4.7 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page