mkdocs-redirects

用于创建页面重定向（例如，对于已移动/重命名的页面）的mkdocs插件。

最初由DataRobot开发。

安装

注意： 此软件包需要MkDocs版本1.0.4或更高版本。

使用pip安装

pip install mkdocs-redirects

使用

要使用此插件，请在您的mkdocs.yml中的插件redirect_maps设置中指定所需的重定向。

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

注意：不要忘记，如果您尚未设置plugins设置，指定该设置将覆盖默认值！有关更多信息，请参阅此页面。

重定向映射应采用键/值对的形式

• 每个重定向的键是原始的 Markdown 文档（相对于 docs_dir 路径）。
  • 此插件将在 mkdocs build 过程中处理文件名解析。这应设置为原始 Markdown 文档的文件名（或如果存在的话将是什么），而不是由 MkDocs 渲染的最终 HTML 文件。
• 值是 重定向目标。它可以采用以下形式
  • 您希望重定向到的 Markdown 文档 的路径（相对于 docs_dir）
    • 此插件将在 mkdocs build 过程中处理文件名解析。这应设置为 Markdown 文档的文件名，而不是由 MkDocs 渲染的最终 HTML 文件。
  • 外部 URL（例如 http://example.com）

在 mkdocs build 过程中，此插件将在 site_dir 中为每个重定向到“新”路径的“旧”文件创建 .html 文件。如果在过程中遇到任何问题或重定向目标实际上不存在，它将产生警告（如果设置了 strict: true 则非常有用）。

use_directory_urls

如果您设置了 use_directory_urls: true（这是默认值），则此插件将修改重定向目标为 目录 URL，而不是实际的 index.html 文件名。但是，它将在正确的位置为每个目标创建 index.html 文件，以便 URL 解析正常工作。

例如，重定向映射 'old/dir/README.md': 'new/dir/README.md' 将导致在 $site_dir/old/dir/index.html 创建一个 HTML 文件，该文件重定向到 ../../new/dir/。

此外，重定向映射 'old/dir/doc_name.md': 'new/dir/doc_name.md' 将导致 $site_dir/old/dir/doc_name/index.html 重定向到 ../../new/dir/doc_name/。

这模仿了在没有此插件的情况下 MkDocs 构建 site 目录的行为。

开发

设置虚拟环境

使用您选择的方法创建一个虚拟环境。

brew install pyenv pyenv-virtualenv
pyenv install 2.7.18
pyenv virtualenv 2.7.18 mkdocs-redirects
pyenv activate mkdocs-redirects

构建

make build

测试

make test

发布

make release

它将提示您输入 PyPI 用户名和密码。

查看

• https://packaging.pythonlang.cn/tutorials/packaging-projects/
• https://packaging.pythonlang.cn/guides/migrating-to-pypi-org/