跳至内容

导航更改 - 管理员或编辑的流程文档

本文档原因

文档项目启动之初，人们希望 Mkdocs 中的菜单尽可能自动化，从而减少手动编辑导航的需求。在生成文档几个月后，很明显，仅仅将文档放在正确的文件夹并让 Mkdocs 生成导航是无法保持整洁有序的。我们需要分类，而 Mkdocs 除非将文档放在特定文件夹中，否则不提供此功能。Mkdocs 将会创建一个按字母顺序排序的导航。然而，创建修复导航的文件夹结构并非全部。即使这样，有时也需要额外的更改来保持组织的条理。例如，在不修改小写文件夹结构的情况下进行大小写调整。

目标

我们的目标是

  • 创建当前所需的文件夹结构（将来可能需要新文件夹）
  • 调整导航，使 Rocky 安装、迁移和贡献区域位于顶部
  • 调整导航，以便更好地命名某些文件夹，并启用正确的大小写。例如，“DNS”和“文件共享服务”否则会显示为“Dns”和“File sharing”，而无需进行一些操作。
  • 确保这些导航文件仅限于管理员和编辑

最后一点对某些读者来说可能显得多余，但随着本文档的继续，它会变得更加明显。

假设

假设您已经克隆了 Rocky GitHub 仓库：https://github.com/rocky-linux/documentation。

环境更改

有了这些更改，就迫切需要“看到”您所做的任何更改在网站上下文中的影响，**在**将内容提交到文档仓库**之前**。

MkDocs 是一个 Python 应用程序，它使用的额外包也是 Python 代码，这意味着运行 MkDocs 所需的环境需要是**正确配置的 Python 环境**。为开发任务（如运行 MkDocs 时）设置 Python 并非易事，本文档的范围不包括这方面的说明。一些注意事项包括

  • Python 版本必须 >= 3.8。此外，**要特别注意不要使用运行 Linux 或 MacOS 的计算机的“系统”Python 版本**。例如，在撰写本文档时，MacOS 上的系统 Python 版本仍然是 2.7 版本。
  • 运行 Python '虚拟环境'。当运行 Python 应用程序项目并安装包（例如 MkDocs）时，Python 社区**强烈建议**为每个项目创建独立的虚拟环境。
  • 使用支持 Python 的现代 IDE（集成开发环境）。两个流行的 IDE，它们也集成了对运行虚拟环境的支持，是

有效地做到这一点需要

  • 使用虚拟环境（见上文）设置一个新的 Python 项目。
  • 安装 mkdocs
  • 安装一些 Python 插件
  • 克隆此 Rocky GitHub 仓库：https://github.com/rocky-linux/docs.rockylinux.org
  • 链接到克隆的文档仓库中的 docs 文件夹（如果需要加载正确的文件夹，您也可以直接修改 mkdocs.yml 文件，但链接可以使您的 mkdocs 环境更整洁）
  • 在克隆的 docs.rockylinux.org 中运行 mkdocs serve

技巧

您可以通过“贡献”菜单的“本地文档”部分中的任何方法来构建完全独立的 mkdocs 环境。

注意

本文档是在 Linux 环境下编写的。如果您的环境不同（Windows 或 Mac），那么您需要研究如何将这些步骤与您的环境相匹配。阅读本文的编辑或管理员可以对此进行更改，以添加适用于那些环境的步骤。

安装

  • 使用 Python 环境安装 mkdocs：pip install mkdocs
  • 安装所需插件：pip install mkdocs-material mkdocs-localsearch mkdocs-awesome-pages-plugin mkdocs-redirects mkdocs-i18n
  • 克隆仓库（如上所述）

链接和运行 mkdocs

在您的 docs.rockylinux.org 本地（克隆）中，执行以下操作。这假定您的文档克隆位置，请根据需要进行修改

ln -s /home/username/documentation/docs docs

同样，您可以更改 mkdocs.yml 文件的本地副本以设置路径。如果使用此方法，您将更改此行以指向您的 documentation/docs 文件夹

docs_dir: 'docs/docs'

完成后，您可以尝试运行 mkdocs serve 来查看您是否获得了想要的内容。这将在您的 localhost 上运行，端口为 8000；例如：http://127.0.0.1:8000/

Mkdocs 使用 .pages 文件**或**通过文档 front matter 中的“title:”值来处理导航。.pages 文件并不复杂，**但是**，如果您遗漏了某项，可能会导致服务器无法加载。这就是为什么此过程**仅**适用于管理员和编辑。这些人将拥有必要的工具（本地安装的 mkdocs，以及文档和 docs.rockylinux.org 的克隆），以便推送到 GitHub 并合并的内容不会破坏文档网站的提供。不期望贡献者拥有这些要求。

.pages 文件

如前所述，.pages 文件通常非常简单。它们是 mkdocs 在渲染内容之前读取的 YAML 格式文件。要查看更复杂的 .pages 文件之一，让我们检查一下用于格式化侧边导航的那个文件

---
nav:
    - ... | index*.md
    - ... | installation*.md
    - ... | migrate2rocky*.md
    - Contribute: contribute
    - Automation: automation
    - Backup & Sync: backup
    - Content Management: cms
    - Communications: communications
    - Containers: containers
    - Database: database
    - Desktop: desktop
    - DNS: dns
    - Email: email
    - File Sharing Services: file_sharing
    - Git: git
    - Interoperability: interoperability
    - Mirror Management: mirror_management
    - Network: network
    - Package Management: package_management
    - ...

在这里，index*.md 显示“Guides Home: ”，installation*.md 显示“Installing Rocky Linux”文档链接，migrate2rocky*.md 显示“Migrating To Rocky Linux”文档链接。每个链接中的 * 允许该文档以任何语言存在，例如 index.fr.md、index.de.md 等。最后，通过将其与“Contribute”并列，它会出现在这些项目之下，而不是正常的（字母顺序）排序。向下看列表，您可以了解每个项目的作用。请注意，在“Package Management: package_management”条目之后，还有两个文件夹（security 和 web）。这些不需要任何额外的格式。.pages 文件告诉 mkdocs 正常加载它们，使用 - ...。

您也可以在实际文件中使用 YAML 格式。这样做的原因可能是文件的开头标题太长，在导航部分显示效果不佳。例如，请看这个文档标题“# mod_ssl on Rocky Linux in an httpd Apache Web-Server Environment”。这太长了。当“Web”导航项打开时，它在侧边导航中显示效果很差。要解决这个问题，您可以与作者合作更改他们的标题，或者，您可以通过在文档中标题之前添加一个 title 来更改它在菜单中的显示方式。在此示例中，为 front matter 添加一个 title 可以缩短列表中标题的长度

---
title: Apache With `mod_ssl`
---

这会改变导航相关的标题，但会保留文档中作者的原始标题。

信息

在大多数情况下，作者的标题将是级别 1 标题，而 title front matter 也将是级别 1（“#”）标题。这会在文档中引入一个 markdown 错误。要解决此问题，您可以删除作者的标题，或将其更改为级别 2 标题（“##”）。

您应该经济地使用 .pages 文件，仅在必要时使用。

结论

虽然使用 .pages 文件进行必要的导航更改并不困难，但存在破坏实时文档的潜在风险。因此，只有拥有适当工具的管理员和编辑才应有权编辑这些文件。拥有完整的环境来查看实时网页的显示情况，可以防止管理员或编辑在编辑这些文件时出错。

作者：Steven Spencer

贡献者：Ezequiel Bruni, Ganna Zhyrnova