模块目录名的建议

当您创建模块目录时，需要考虑团队将如何使用存储在其中的文件以及它们的名称将如何影响您网站的 URL 。

选择模块文件夹名称

Antora 根据模块文件夹的名称中分配模块的名称。模块名用作页面、图像、附件、示例和部分的资源 id 中的模块坐标。它还用于分配给该模块的可发布资源的 url 中(除了 ROOT 模块)。

在选择模块文件夹名称时，请记住以下要求和建议：

  • 命名模块目录不能包含空白或前向斜线(/)。这些字符不允许在 Asciidoc 交叉参考，图像宏或包括指令的目标中。

  • 请尽量避免在 url 中使用大写字母、下划线等不推荐使用的字符。这样的字符会限制 web 服务器的可移植性，降低站点搜索结果，并导致访问者可访问性问题。

  • 如果您的团队经常跨模块引用资源，他们将不得不在资源 id 中键入模块名称，因此不要将文件夹名称以及模块名称设置得太长或难以记住。好的模块名是简短且具有描述性的。

示例1显示了一组标准目录，其中包含三个命名模块目录。

Example 1. Example 1. Three named module directories
📒 repository
  📂 docs
    📄 antora.yml
    📂 modules
      📂 gear (1)
        📂 images
          📄 image-source-file.ext
      📂 la-garita (2)
        📂 pagesAlian
          📄 page-source-file.adoc
      📂 ROOT (3)
        📂 pagesAlian
          📄 page-source-file.adoc
        📄 nav.adoc
      📂 sdk (4)
        📂 examples
          📄 demo-source-file.ext
        📂 pagesAlian
          📄 page-source-file.adoc
        📄 nav.adoc
1 模块目录名为 gear
2 名为 la-garita 的模块目录
3 根模块目录
4 名为sdk的模块目录

Antora 将从例 1 中命名的模块目录中计算出以下模块名称: gear 、la-garita 和 sdk 。