| Name | mkdocs-redirects JSON |
| Version |
1.2.2
JSON |
| download |
| home_page | None |
| Summary | A MkDocs plugin for dynamic page redirects to prevent broken links |
| upload_time | 2024-11-07 14:57:21 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | None |
| keywords |
mkdocs
mkdocs-plugin
redirect
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# 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/).
[](https://pypi.org/project/mkdocs-redirects/)
[](https://github.com/mkdocs/mkdocs-redirects/blob/master/LICENSE.md)
[](https://github.com/mkdocs/mkdocs-redirects/actions?query=event%3Apush+branch%3Amaster)
## Installing
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
Dev dependencies and tasks are managed with [Hatch](https://hatch.pypa.io/). Tasks run in their own environment, created on the fly if missing, in a separate directory tree.
To run all checks and fixes:
```bash
hatch run all
```
You can learn about individual commands from the output, or by inspecting `scripts` in [pyproject.toml](pyproject.toml).
## Releasing
A release is published to PyPI through GitHub Actions whenever a new tag is pushed.
So, to create a release, run `.tools/release.sh x.y.z` (which bumps the version in `__init__.py`, checks the build, creates a commit and a tag `vx.y.z`, and pushes it to GitHub).
Then fill out a GitHub release with release notes.
Raw data
{
"_id": null,
"home_page": null,
"name": "mkdocs-redirects",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "mkdocs, mkdocs-plugin, redirect",
"author": null,
"author_email": "Dustin Burke <dustin@datarobot.com>",
"download_url": "https://files.pythonhosted.org/packages/f1/a8/6d44a6cf07e969c7420cb36ab287b0669da636a2044de38a7d2208d5a758/mkdocs_redirects-1.2.2.tar.gz",
"platform": null,
"description": "# mkdocs-redirects\n\n**Plugin 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[](https://pypi.org/project/mkdocs-redirects/)\n[](https://github.com/mkdocs/mkdocs-redirects/blob/master/LICENSE.md)\n[](https://github.com/mkdocs/mkdocs-redirects/actions?query=event%3Apush+branch%3Amaster)\n\n## Installing\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** \n> 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\nDev dependencies and tasks are managed with [Hatch](https://hatch.pypa.io/). Tasks run in their own environment, created on the fly if missing, in a separate directory tree.\n\nTo run all checks and fixes:\n\n```bash\nhatch run all\n```\n\nYou can learn about individual commands from the output, or by inspecting `scripts` in [pyproject.toml](pyproject.toml).\n\n## Releasing\n\nA release is published to PyPI through GitHub Actions whenever a new tag is pushed.\n\nSo, to create a release, run `.tools/release.sh x.y.z` (which bumps the version in `__init__.py`, checks the build, creates a commit and a tag `vx.y.z`, and pushes it to GitHub).\n\nThen fill out a GitHub release with release notes.\n",
"bugtrack_url": null,
"license": null,
"summary": "A MkDocs plugin for dynamic page redirects to prevent broken links",
"version": "1.2.2",
"project_urls": {
"Documentation": "https://github.com/mkdocs/mkdocs-redirects#readme",
"History": "https://github.com/mkdocs/mkdocs-redirects/releases",
"Issues": "https://github.com/mkdocs/mkdocs-redirects/issues",
"Source": "https://github.com/mkdocs/mkdocs-redirects"
},
"split_keywords": [
"mkdocs",
" mkdocs-plugin",
" redirect"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c4ec38443b1f2a3821bbcb24e46cd8ba979154417794d54baf949fefde1c2146",
"md5": "151ddd5405273bacb1b26268069128bc",
"sha256": "7dbfa5647b79a3589da4401403d69494bd1f4ad03b9c15136720367e1f340ed5"
},
"downloads": -1,
"filename": "mkdocs_redirects-1.2.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "151ddd5405273bacb1b26268069128bc",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 6142,
"upload_time": "2024-11-07T14:57:19",
"upload_time_iso_8601": "2024-11-07T14:57:19.143832Z",
"url": "https://files.pythonhosted.org/packages/c4/ec/38443b1f2a3821bbcb24e46cd8ba979154417794d54baf949fefde1c2146/mkdocs_redirects-1.2.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f1a86d44a6cf07e969c7420cb36ab287b0669da636a2044de38a7d2208d5a758",
"md5": "1080b1ed4b5588413af1394ed99f82cf",
"sha256": "3094981b42ffab29313c2c1b8ac3969861109f58b2dd58c45fc81cd44bfa0095"
},
"downloads": -1,
"filename": "mkdocs_redirects-1.2.2.tar.gz",
"has_sig": false,
"md5_digest": "1080b1ed4b5588413af1394ed99f82cf",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 7162,
"upload_time": "2024-11-07T14:57:21",
"upload_time_iso_8601": "2024-11-07T14:57:21.109583Z",
"url": "https://files.pythonhosted.org/packages/f1/a8/6d44a6cf07e969c7420cb36ab287b0669da636a2044de38a7d2208d5a758/mkdocs_redirects-1.2.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-07 14:57:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mkdocs",
"github_project": "mkdocs-redirects#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mkdocs-redirects"
}
