# mkdocs-redirects
Plugin for [`mkdocs`](https://www.mkdocs.org/) to create page redirects (e.g. for moved/renamed pages).
Initially developed by [DataRobot](https://www.datarobot.com/).
## Installing
> **Note:** This package requires MkDocs version 1.0.4 or higher.
Install with pip:
```bash
pip install mkdocs-redirects
```
## Using
To use this plugin, specify your desired redirects in the plugin's `redirect_maps` setting in your `mkdocs.yml`:
```yaml
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](https://www.mkdocs.org/user-guide/configuration/#plugins) 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 mimics the behavior of how MkDocs builds the site dir without this plugin.
## Developing
### Setup a virtualenv
Create a virtualenv using a method of your choice.
```bash
brew install pyenv pyenv-virtualenv
pyenv install 2.7.18
pyenv virtualenv 2.7.18 mkdocs-redirects
pyenv activate mkdocs-redirects
```
### Build
```bash
make build
```
### Test
```bash
make test
```
## Releasing
```bash
make release
```
It will prompt you for your PyPI user and password.
See:
- <https://packaging.python.org/tutorials/packaging-projects/>
- <https://packaging.python.org/guides/migrating-to-pypi-org/>
Raw data
{
"_id": null,
"home_page": "https://github.com/datarobot/mkdocs-redirects",
"name": "mkdocs-redirects",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "mkdocs redirect",
"author": "Dustin Burke",
"author_email": "dustin@datarobot.com",
"download_url": "https://files.pythonhosted.org/packages/04/6a/50edd7ad78042b25c379aac7e8fa9cc34c6f55e3d2c03eb28814a9446617/mkdocs-redirects-1.2.1.tar.gz",
"platform": null,
"description": "# mkdocs-redirects\n\nPlugin for [`mkdocs`](https://www.mkdocs.org/) to create page redirects (e.g. for moved/renamed pages).\n\nInitially developed by [DataRobot](https://www.datarobot.com/).\n\n## Installing\n\n> **Note:** This package requires MkDocs version 1.0.4 or higher.\n\nInstall with pip:\n\n```bash\npip install mkdocs-redirects\n```\n\n## Using\n\nTo use this plugin, specify your desired redirects in the plugin's `redirect_maps` setting in your `mkdocs.yml`:\n\n```yaml\nplugins:\n - redirects:\n redirect_maps:\n 'old.md': 'new.md'\n 'old/file.md': 'new/file.md'\n 'some_file.md': 'http://external.url.com/foobar'\n```\n\n_Note: don't forget that specifying the `plugins` setting will override the defaults if you didn't already have it set! See [this page](https://www.mkdocs.org/user-guide/configuration/#plugins) for more information._\n\nThe redirects map should take the form of a key/value pair:\n\n- The key of each redirect is the original _markdown doc_ (relative to the `docs_dir` path).\n - This plugin will handle the filename resolution during the `mkdocs build` process.\n 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\n- The value is the _redirect target_. This can take the following forms:\n - Path of the _markdown doc_ you wish to be redirected to (relative to `docs_dir`)\n - This plugin will handle the filename resolution during the `mkdocs build` process.\n This should be set to what the markdown doc's filename is, not the final HTML file rendered by MkDocs\n - External URL (e.g. `http://example.com`)\n\nDuring 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.\nIt 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).\n\n### `use_directory_urls`\n\nIf 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.\nHowever, it will create the `index.html` file for each target in the correct place so URL resolution works.\n\nFor 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/`.\n\nAdditionally, 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/`.\n\nThis mimics the behavior of how MkDocs builds the site dir without this plugin.\n\n## Developing\n\n### Setup a virtualenv\n\nCreate a virtualenv using a method of your choice.\n\n```bash\nbrew install pyenv pyenv-virtualenv\npyenv install 2.7.18\npyenv virtualenv 2.7.18 mkdocs-redirects\npyenv activate mkdocs-redirects\n```\n\n### Build\n\n```bash\nmake build\n```\n\n### Test\n\n```bash\nmake test\n```\n\n## Releasing\n\n```bash\nmake release\n```\n\nIt will prompt you for your PyPI user and password.\n\nSee:\n\n- <https://packaging.python.org/tutorials/packaging-projects/>\n- <https://packaging.python.org/guides/migrating-to-pypi-org/>\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A MkDocs plugin for dynamic page redirects to prevent broken links.",
"version": "1.2.1",
"project_urls": {
"Homepage": "https://github.com/datarobot/mkdocs-redirects"
},
"split_keywords": [
"mkdocs",
"redirect"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "046a50edd7ad78042b25c379aac7e8fa9cc34c6f55e3d2c03eb28814a9446617",
"md5": "fc2c6cd1cc9a5d4a546af778a1a7af57",
"sha256": "9420066d70e2a6bb357adf86e67023dcdca1857f97f07c7fe450f8f1fb42f861"
},
"downloads": -1,
"filename": "mkdocs-redirects-1.2.1.tar.gz",
"has_sig": false,
"md5_digest": "fc2c6cd1cc9a5d4a546af778a1a7af57",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 6653,
"upload_time": "2023-07-18T21:26:18",
"upload_time_iso_8601": "2023-07-18T21:26:18.016281Z",
"url": "https://files.pythonhosted.org/packages/04/6a/50edd7ad78042b25c379aac7e8fa9cc34c6f55e3d2c03eb28814a9446617/mkdocs-redirects-1.2.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-18 21:26:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "datarobot",
"github_project": "mkdocs-redirects",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mkdocs-redirects"
}
JSON
