跳至内容

导航更改 - 面向经理或编辑的流程文档

本文件的原因

在文档项目开始时，人们希望 Mkdocs 中的菜单尽可能地自动化，从而使手动导航编辑变得很少。在生成文档几个月后，很明显，仅仅将文档放在正确的文件夹中并让 Mkdocs 生成导航并不能依赖于保持事物的整洁和井井有条。我们需要类别，而 Mkdocs 除非将文档放在特定文件夹中，否则不会提供类别。然后 Mkdocs 将创建一个带有字母顺序排序的导航。但是，创建修复导航的文件夹结构并非全部。即使这样有时也需要额外的更改才能保持组织。例如，在不修改小写文件夹结构的情况下进行大写。

目标

我们的目标是

  • 根据现在的需要创建文件夹结构（将来可能需要新的文件夹）
  • 调整导航，以便 Rocky 安装、迁移和贡献区域位于顶部
  • 调整导航以更好地命名一些文件夹，并启用正确的大写。例如，"DNS" 和 "File Sharing Services" 否则显示为 "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，看看是否能获取到您想要的内容。这将在您的本地主机上的端口 8000 上运行；例如：http://127.0.0.1:8000/

Mkdocs 使用.pages 文件或文档前置内容中的“title:” 元数据的来处理导航。.pages 文件并不复杂，但如果您遗漏了什么，它会导致服务器无法加载。这就是为什么此过程仅适用于管理者和编辑人员。这些人将拥有必要的工具（本地安装的 mkdocs 以及 documentation 和 docs.rockylinux.org 的克隆），因此推送到 GitHub 并合并到 GitHub 的内容不会中断文档网站的提供。贡献者不需要满足这些要求。

.pages 文件

如前所述，.pages 文件通常非常简单。它们是 mkdocs 在渲染内容之前读取的 YAML 格式文件。为了查看更复杂的 .pages 文件之一，让我们检查一下为帮助格式化侧边导航而创建的 .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 显示“指南首页：”，installation*.md 显示“安装 Rocky Linux”文档链接，而 migrate2rocky*.md 显示“迁移到 Rocky Linux”文档链接。每个链接中的 * 允许该文档以任何语言存在，例如，index.fr.md、index.de.md 等等。最后，通过将“贡献”置于下一个位置，它将显示在这些项目下方，而不是按正常（字母）排序顺序显示。向下查看列表，您可以看到每个项目的作用。请注意，在“包管理：package_management”条目之后，还有两个文件夹（security 和 web）存在。这些不需要任何额外的格式化。.pages 文件告诉 mkdocs 以正常方式加载它们，使用 - ...。

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

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

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

信息

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

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

结论

虽然使用 .pages 文件进行必要的导航更改并不困难，但存在破坏实时文档的可能性。出于这个原因，只有拥有适当工具的管理者和编辑人员才有权编辑这些文件。拥有可用于查看实时网页显示的完整环境可以让管理者或编辑人员在编辑这些文件时避免犯错。

作者：Steven Spencer

贡献者：Ezequiel Bruni, Ganna Zhyrnova