{"id":2995,"library":"mkdocs-redirects","title":"MkDocs Redirects Plugin","description":"mkdocs-redirects is a plugin for MkDocs that provides dynamic page redirects, crucial for maintaining link integrity when restructuring documentation. As of version 1.2.3, it offers robust mapping capabilities for internal and external links. The project is under active development, with a recent transition to a new organizational umbrella, ProperDocs, signaling continued evolution.","status":"active","version":"1.2.3","language":"en","source_language":"en","source_url":"https://github.com/ProperDocs/mkdocs-redirects","tags":["mkdocs","plugin","redirects","documentation","static-site-generator"],"install":[{"cmd":"pip install mkdocs-redirects","lang":"bash","label":"Install with pip"}],"dependencies":[],"imports":[{"note":"Users enable and configure this plugin by adding it to the `plugins` section of their MkDocs configuration file, typically `mkdocs.yml`.","symbol":null,"correct":"Not imported directly in Python code. Configured via mkdocs.yml."}],"quickstart":{"code":"# mkdocs.yml\nsite_name: My Awesome Docs\n\nplugins:\n  - redirects:\n      redirect_maps:\n        'old-page.md': 'new-page.md'\n        'blog/legacy-post.md': '/blog/current-post/' # Absolute path within site\n        'external-link.md': 'https://example.com/new-resource'\n        'docs/old-section/chapter-1.md': '../new-section/chapter-1.md' # Relative to docs_dir\n","lang":"yaml","description":"To enable `mkdocs-redirects`, add it to the `plugins` section of your `mkdocs.yml` file. Define redirect mappings using `redirect_maps`, where keys are old paths (relative to `docs_dir`) and values are new paths (can be internal relative, absolute, or external URLs)."},"warnings":[{"fix":"For long-term compatibility and to align with the project's evolving direction, consider exploring the ProperDocs ecosystem and its `properdocs` executable. Refer to the ProperDocs discussions for more details: `https://github.com/ProperDocs/properdocs/discussions/33`.","message":"The project maintainers are transitioning to a new organization, ProperDocs, and are encouraging the use of the `properdocs` executable over the traditional `mkdocs` executable. While `mkdocs-redirects` still functions with `mkdocs`, future versions and features may prioritize the ProperDocs ecosystem.","severity":"breaking","affected_versions":"1.2.3 and onwards"},{"fix":"Upgrade your Python environment to 3.10 or newer. Python 3.14 is officially supported.","message":"Python 3.9 support has been officially dropped.","severity":"breaking","affected_versions":"1.2.3 and onwards"},{"fix":"Carefully verify redirect paths. For internal redirects, it is often safer and clearer to use absolute paths (e.g., `/new-page/`) for target URLs. Thoroughly test all redirects after configuration changes to prevent broken links.","message":"Paths specified in `redirect_maps` are interpreted relative to your `docs_dir` (e.g., `docs/` by default) for the 'old path' keys. For 'new path' values, absolute paths (starting with `/`) are relative to the site root, and external URLs (starting with `http/https`) are handled directly. Relative paths in values (e.g., `../new-page.md`) are interpreted relative to the source file's location within `docs_dir`.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Align your redirect target paths with the URL structure generated by MkDocs based on your `use_directory_urls` setting. If `use_directory_urls` is `true`, use directory-style paths for targets; if `false`, use `.html` suffixes.","message":"If `use_directory_urls` is enabled in your `mkdocs.yml` (which is the default behavior), ensure your redirect target paths in `redirect_maps` reflect the directory-style URL structure (e.g., `new-page/` instead of `new-page.md`). Mixing styles can lead to unexpected redirect behavior.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}