I am currently writing and moving files for the documentation of https://docs.retest.de. Thus I find your plugin very helpful to specify the redirect to the new pages.

However, with following configuration, I get an error under Windows (full setup):

plugins:
  - search
  - redirects:
      redirect_maps:
        "recheck/how-ignore-works-in-recheck.md": "recheck/how-ignore-works.md"

WARNING -  Redirect target 'recheck/how-ignore-works.md' does not exist! 

As so often, a change to the os dependent path separator does the trick. I just needed to adjust the new page with the separators. The old does work with both.

"recheck/how-ignore-works-in-recheck.md": "recheck\\how-ignore-works.md"

However, we deploy our site to github pages. Thus we need the linux separators, while still being able to serve the site locally while expanding the documentation and testing if the redirect works properly. While one can use WSL, it would be more comfortable if it works on both systems.

To verify the problem is properly solved for linux, I switched to WSL (Debian). I was able to properly serve this page and follow the redirect (see retest/docs#47).

Setup

Full setup available here.

• VSCode: Use to write documentation, execute mkdocs serve as well as connect to WSL.

Tested on following operating systems:

• Windows 10
  • python 3.7.4
  • pip 19.2.3
• WSL (Debian)
  • python 3.7.3
  • pip 18.1

MkDocs:

• mkdocs
• mkdocs-material
• mkdocs-redirects

Unfortunately I do not have the time to do a proper PR, thus only this issue.

Right now it only allows a 1-1 correspondance. Sometimes when migrating documentation you may find yourself that externally referenced links may be broken.

If this plugin allows you to select regular expressions, it removes the need of any external redirection, such as one you could do by yourself with nginx.

Do the current maintainers have any plans to continue working on this package (i.e. merging the pending fixes and releasing them)? If not, would you be open to handing over maintenance?

I'm the current maintainer of MkDocs itself, and I offer to maintain this package, including moving it to mkdocs organization if necessary.

@burkestar @carsongee

Continuing from #23 (comment)

When I create a redirect from "aaanbbbcdsc" to "index.md" Firefox tries to download the file. What am I missing?

When installing mkdocs-redirects, a missing dependency "testresources" is mentioned.
Usage of mkdocs-redirects seems not to affected, but would be nice not having this error message.

$ pip --version
pip 21.3.1 from /usr/local/lib/python3.8/dist-packages/pip (python 3.8)

// Ensure cache is empty
$ pip cache purge

$ pip install mkdocs-redirects
Defaulting to user installation because normal site-packages is not writeable
Collecting mkdocs-redirects
  Downloading mkdocs-redirects-1.0.3.tar.gz (5.1 kB)
  Preparing metadata (setup.py) ... done
Collecting mkdocs<2,>=1.0.4
  Downloading mkdocs-1.2.3-py3-none-any.whl (6.4 MB)
     |████████████████████████████████| 6.4 MB 3.0 MB/s            
[...]
Successfully built mkdocs-redirects
Installing collected packages: six, zipp, python-dateutil, MarkupSafe, watchdog, pyyaml-env-tag, packaging, mergedeep, Markdown, Jinja2, importlib-metadata, ghp-import, mkdocs, mkd
ocs-redirects


ERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behaviour is the source of the following dependency conflicts.
launchpadlib 1.10.13 requires testresources, which is not installed. // <!---------------------------------------------------------


Successfully installed Jinja2-3.0.3 Markdown-3.3.4 MarkupSafe-2.0.1 ghp-import-2.0.2 importlib-metadata-4.8.2 mergedeep-1.3.4 mkdocs-1.2.3 mkdocs-redirects-1.0.3 packaging-21.2 python-dateutil-2.8.2 pyyaml-env-tag-0.1 six-1.16.0 watchdog-2.1.6 zipp-3.6.0

I've got a small script going that will generate a new mkdocs.yml file from any renamed files in git status. It'd be nice to have a similar functionality with this plugin that will automatically add the redirects for me as it's quite a laborious process to add each individual change (especially for large changes) at once.

Is this something we could look into?

Thanks for the awesome plugin!

Hi everyone

I'm facing an issue with your amazing plugin.
Sadly it's only reproductible on a windows environment.

When we put a redirect containing special UTF-8 characters like below, the request on the corresponding page returns a 404 code.

    - redirects:
        redirect_maps:
            'index.md': 'présentation/index.md'

If we check the html generating the redirect, we could observe the following output :

$ curl http://127.0.0.1:8000

<!doctype html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>Redirecting...</title>
    <link rel="canonical" href="pr�sentation/">
    <meta name="robots" content="noindex">
    <script>var anchor=window.location.hash.substr(1);location.href="pr�sentation/"+(anchor?"#"+anchor:"")</script>
    <meta http-equiv="refresh" content="0; url=pr�sentation/">
</head>
<body>
Redirecting...
</body>
</html>

To compare with a linux environment (WSL2)

$ curl http://127.0.0.1:8000

<!doctype html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>Redirecting...</title>
    <link rel="canonical" href="présentation/">
    <meta name="robots" content="noindex">
    <script>var anchor=window.location.hash.substr(1);location.href="présentation/"+(anchor?"#"+anchor:"")</script>
    <meta http-equiv="refresh" content="0; url=présentation/">
</head>
<body>
Redirecting...
</body>
</html>

As we can see the href is not proper managed and the redirection is therefore broken.

Do you have any idea on how to fix this issue ? I'm not really friendly with python, so it will be difficult for me to investigate this issue.

Please note that I use these versions :

• windows 10.0.19044
• python 3.10
• mkdocs 1.3.1

Thanks in advance

On Windows this creates:

<!doctype html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>Redirecting...</title>
    <link rel="canonical" href="..\abc\def.html">
    <meta name="robots" content="noindex">
    <script>var anchor=window.location.hash.substr(1);location.href="..\abc\def.html"+(anchor?"#"+anchor:"")</script>
    <meta http-equiv="refresh" content="0; url=..\abc\def.html">
</head>
<body>
Redirecting...
</body>
</html>

I assume using os.path.join is the cause issues, especially when not converting to valid URL at the end.

An alternate way to configure the redirections would be to use symlinks in the docs/ directory. That way it would not require editing the mkdocs.yaml file for every redirect and might be an easier way to manage the files.

My docs website lives at https://rojo.space/docs, a part of a larger website not managed by MkDocs.

I have a redirect setup like this:

  - redirects:
      redirect_maps:
        'latest/index.md': 'index.md'

I'm expecting this to redirect from https://rojo.space/docs/latest to https://rojo.space/docs, but it instead redirects to https://rojo.space.

I would expect mkdocs-redirects to use the site_url configuration value to know that my docs website is not at the root, and generate appropriate redirects. It is set to https://rojo.space/docs for this site.

I would like to redirect from '/this-folder/' to '/another-folder/' or '/to-here/index.html'

When the HTML output files are accessed locally (file:// protocol), the redirects don't work.

This is because of the leading slash in the redirect target.

Tested in Firefox and Chrome.

mkdocs.yml

use_directory_urls: false
plugins:
    - redirects:
        redirect_maps:
            'old.md': 'new.md'

old.html

<!doctype html>
<html lang="en">

<head>
    <meta charset="utf-8">
    <title>Redirecting...</title>
    <link rel="canonical" href="/new.html">
    <meta name="robots" content="noindex">
    <script>var anchor = window.location.hash.substr(1); location.href = "/new.html" + (anchor ? "#" + anchor : "")</script>
    <meta http-equiv="refresh" content="0; url=/new.html">
</head>

<body>
    Redirecting...
</body>

</html>

Solution

If I manually replace /new.html by new.html, everything works fine, both locally and on the web, and both in Chrome and Firefox.

Every time I run mkdocs serve I get this message

INFO    -  DeprecationWarning: warning_filter doesn't do anything since MkDocs
           1.2 and will be removed soon. All messages on the `mkdocs` logger get
           counted automatically.
             File
           "/Library/Frameworks/Python.framework/Versions/3.8/lib/python3.8/site-packages/mkdocs_redirects/plugin.py",
           line 15, in <module>
               log.addFilter(utils.warning_filter)
             File
           "/Library/Frameworks/Python.framework/Versions/3.8/lib/python3.8/site-packages/mkdocs/utils/__init__.py",
           line 453, in __getattr__
               warnings.warn(

I was wondering, if the redirects created by this plugin do support header links.

For example:
Would a configuration that redirects old_page.md to new_page.md make https://example.com/old_page#header redirect to https://example.com/new_page#header?

From my basic testing does this not seem to be the case and I'm not sure if that is doable with redirects.

(see also PR #50)

I would like to use mkdocs-redirects in our effort to port our documentation from Sphinx/.rst (hosted at ReadTheDocs to MkDocs/.md (hosted at GitHub Pages), so we can avoid breaking our current documentation URLs.

This is actually working already, by using something like:

plugins:
  - redirects:
      redirect_maps:
        en/latest/example.html: example.md

This makes a URL like https://example.github.io/docs/en/latest/exampe.html redirect correctly to https://example.github.io/docs/example/.

The problem is that mkdocs-redirects currently logs a warning for redirects of non-MarkDown paths:

WARNING  -  redirects plugin: 'en/latest/example.html' is not a valid markdown file!

That's annoying, since we would like to use mkdocs build --strict in CI to test changes to our documentation, and that exits with a non-zero exit code as soon there as any warnings.

Two potential ways forward:

• disable the warning for .html paths (since it works fine);
• add support for a way to opt-in to redirecting .html paths, through a configuration option like allow_html_redirect (implemented in #50);

Hi!

I have a site http://example-site1.com/example/error-description-1.html created with mkdocs (example/error-description-1.md)

This site is accessed from Linux, which escapes symbols like this: http:\/\/example-site1.com\/example\/error-description-1.html

If you just copy this link and paste to a browser you will get this: http://example-site1.com//example//error-description-1.html

I need to create redirection from broken link http://example-site1.com//example//error-description-1.html to correct link http://example-site1.com/example/error-description-1.html.

Can I do this with your plugin?

Hello!

Sometimes, in large base documentation evolving for a few years, it's quite hard to maintain a healthy redirections mapping and it's not really convenient as it's stored within the mkdocs.yml.

Why not allowing to load redirections map from an external file, for example a CSV with an option (mutually exclusive with redirect_maps) like this:

plugins:
    - redirects:
        redirect_file: "config/redirections.csv"

First of all: this is a very useful plugin, thanks for writing it!

I'm currently in the process of rewriting the docs for Material for MkDocs in squidfunk/mkdocs-material#1735 and, as the overall structure changed a lot, want to redirect some of the pages. However, some pages were merged.

Idea

Allow hash fragments in URL mappings, so that the redirect will jump to the subsection of the page, e.g.:

plugins:
  - search
  - redirects:
      redirect_maps:
        releases/4.md: upgrading.md#upgrading-to-4-x
        releases/5.md: upgrading.md#upgrading-to-5-x
        releases/changelog.md: changelog.md

Actual behavior

When building the site, the plugin prints:

WARNING -  Redirect target 'upgrading.md#upgrading-to-4-x' does not exist! 
WARNING -  Redirect target 'upgrading.md#upgrading-to-5-x' does not exist! 

Desired behavior

No error, redirects work.

Hey,

Redirection fails when you have the following mkdocs.yaml configuration:

extra:
  my_url: https://google.com

redirect-page.md

redirect: {{ my_url }}

The {{ my_url }} variable is treated as a literal and the redirection link becomes http://host/%7B%7B%20my_url%20%7D%7D.

The sdists on PyPI do not contain the LICENSE file. please add

license_files=['LICENSE']

to setup.py to amend for this. In the meantime, could the 1.0.3 release be tagged on GitHub, so that the GitHub archive can be used instead?

Using Material for MkDocs (https://squidfunk.github.io/mkdocs-material/), adding the redirect plugin fails to result in successful redirects for any internal documentation links to the redirected page, as well as the nav bar.

Configuration setting used:

plugins:
  redirects:
    redirect_maps:
      "old.md": "new.md"

This produces the following warnings:

WARNING  -  A relative path to 'old.md' is included in the 'nav' configuration, which is not found in the documentation files
WARNING  -  Documentation file 'Frequently_Asked_Questions_FAQ_.md' contains a link to 'old.md' which is not found in the documentation files.
WARNING  -  Documentation file 'More_docs.md' contains a link to 'old.md' which is not found in the documentation files.

and trying to open the links with the WARNING message opens the 404 page of the docs.

Is there a specific incompatibility with Material for MkDocs?

Is there a way to redirect to an existing .html file? I previously used the now deprecated redirect: in the .md file to redirect to an .html that was already generated using other software. From what I can tell, this plugin only allows you to specify .md files, which effectively would prevent me from using raw .html redirect.

For example, if I have an .html file called /docs/content/page.html and I want an index.html generated by mkdocs to redirect to it, I previously just put redirect: page.html in /docs/content.md, and I would automatically be redirected to page.html when I navigated to the /docs/content page.

Is there any way to achieve this effect with the mkdocs-redirects plugin?

cat >mkdocs.yml

site_name: test
use_directory_urls: false

theme:
  name: material

plugins:
  - redirects:
      redirect_maps:
        foo.md: foo/README.md

mkdir -p docs/foo
touch docs/foo/README.md
pip install -U mkdocs-redirects==1.0.2
mkdocs build
cat site/foo.html                        

<!doctype html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>Redirecting...</title>
    <link rel="canonical" href="foo/README.html">
    <meta name="robots" content="noindex">
    <script>var anchor=window.location.hash.substr(1);location.href="foo/README.html"+(anchor?"#"+anchor:"")</script>
    <meta http-equiv="refresh" content="0; url=foo/README.html">
</head>
<body>
Redirecting...
</body>
</html>

In the above example you can see a problem: MkDocs doesn't produce a file "README.html"; instead it is "index.html", so the redirect is broken.
Previously it worked well:

pip install -U mkdocs-redirects==1.0.1
mkdocs build
cat site/foo.html                        

<!doctype html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>Redirecting...</title>
    <link rel="canonical" href="/foo/index.html">
    <meta name="robots" content="noindex">
    <script>var anchor=window.location.hash.substr(1);location.href="/foo/index.html"+(anchor?"#"+anchor:"")</script>
    <meta http-equiv="refresh" content="0; url=/foo/index.html">
</head>
<body>
Redirecting...
</body>
</html>

I believe this is a direct consequence of #19 (cc @plannigan).

#21 has no effect on it; v1.0.3 is still broken.

Hello,

Now I want to use mkdocs-redirects to redirect from a old layout to a new docs layout including subfolders and translated pages using https://github.com/ultrabug/mkdocs-static-i18n
But I have a small problem:
Lets assume following redirection:
'old_foo.md': 'bar/foo.en.md'
Normally it should redirect to bar/foo/ but it builds a redirection to bar/foo.en/ and this pages doesn't exist.

Not sure if this can be fixed, since files can be named xx.en but maybe you guys have a solution for me.

I believe v1.0.4 resolves issue #24, but introduces the same result when use_directory_urls is set to false.

use_directory_urls: false

theme:
  name: "material"

plugins:
- redirects:
    redirect_maps:
      index.md: readme.md

When defining redirects for Material for MkDocs' new built-in blog plugin, I stumbled upon a problem where computed URLs are not taken into account. The blog plugin recursively enumerates all Markdown files in the folder docs/blog/posts and then rewrites the File objects to have the correct dest_path and url values in the on_files hook. This is done so MkDocs and other plugins know the correct destinations for all blog posts. The result looks like this:

File(
  src_path='blog/posts/blog-support-just-landed.md', 
  dest_path='blog/2022/09/12/blog-support-just-landed/index.html', 
  name='blog-support-just-landed', 
  url='blog/2022/09/12/blog-support-just-landed/'
)

Now, when I map the old paths to the new src_path, the redirects plugin will ignore the computed, file.url and compute the target URL by itself, resulting in blog/posts/blog-support-just-landed/, which mismatches the destination URL.

Possible fix in #45.

I'm trying to be more consistent with my Guide that runs on mkdocs

and i have a few pages i want to switch from upper case to lower case, but wanted for compatibility create redirects

Sonarr/Sonarr-recommended-naming-scheme.md: Sonarr/sonarr-recommended-naming-scheme.md
Sonarr/Sonarr-Release-Profile-RegEx.md: Sonarr/sonarr-release-profile-regex.md
Sonarr/Sonarr-remote-path-mapping.md: Sonarr/sonarr-remote-path-mapping.md

But when testing this on my local setup it looks like it loops or get's stuck

Personally, I feel like it could be a nice feature to allow defining redirects in a file's yaml frontmatter.

As an example:

---
title: Title
description: Some page.

redirects:
  - old/location/index.md
---

# Title

Content

The benefits I see:

• More organized. It's clear what old locations redirect to this page
• Easier to edit. Move file, edit it vs. Move file, go to mkdocs.yml and edit it.

It's just a random idea that came to mind.

Hello!

This looks like a cool plugin that I would love to use, but I would need pre-built wheels so that the time it takes to install the plugin is reduced. This is super simple, it would just require changing setup.py sdist into setup.py sdist bdist_wheel in the Makefile.

Thanks in advance.

Now mkdocs-redirect create both source and target redirect URLs based on mkdocs option use_directory_urls
But if we had a legacy site with file-style URLs and now we need redirects from that old legacy to new shiny site with fancy URL redirects we are out of luck :(

So I end with that hack:
https://github.com/andgineer/TRegExpr/blob/master/docs/fix_folder_redirects.py

To fix that for example we can have mkdocs-redict option use different use_directory_urls for the redirect sources.

Also we could specify that for each redirect.

I stumbled on this when looking into #23. The key difference is use_directory_urls is set to true in this case.

mkdocs.yml

site_name: test
use_directory_urls: true

theme:
  name: material

plugins:
  - redirects:
      redirect_maps:
        foo.md: foo/README.md

Note that with use_directory_urls enabled, the original markdown do is the same as the redirect target. This results in the redirect output file being generated on top of the file generated by mkdocs. It appears that the only productive thing the plugin can do in this situation is true raise an error.

This occurs in both v1.0.1 & v1.0.3. This occurs for when the redirect target is README.md or index.md.

Commands to reproduce:

mkdir -p docs/foo
touch docs/foo/README.md
pip install -U mkdocs-redirects==1.0.3
mkdocs build

site/foo/index.html

<!doctype html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>Redirecting...</title>
    <link rel="canonical" href="./">
    <meta name="robots" content="noindex">
    <script>var anchor=window.location.hash.substr(1);location.href="./"+(anchor?"#"+anchor:"")</script>
    <meta http-equiv="refresh" content="0; url=./">
</head>
<body>
Redirecting...
</body>
</html>