模块目录名称建议

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

选择模块文件夹名称

Antora会根据模块的名称从模块文件夹的名称分配模块名称。模块名称用作页面、图片、附件、示例和部分资源ID中的模块坐标。它还用于分配给该模块的可发布资源的URL（除了ROOT模块）。

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

  • 命名的模块目录不能包含空格或斜杠（/）。这些字符不允许出现在AsciiDoc交叉引用、图片宏或包含指令的目标中。

  • 如果可能的话，不要使用大写字母、下划线（_）和其他不推荐在URL中使用的字符。这些字符可能会限制Web服务器的可移植性，降低站点搜索结果，并导致访问者的可访问性问题。

  • 如果您的团队经常跨模块引用资源，他们将不得不在资源ID中输入模块的名称，因此不要使文件夹名称，以及模块名称，过长或难以记忆。良好的模块名称应该简短且描述性。

示例1展示了一个包含三个命名模块目录的标准目录集。

示例1. 三个命名模块目录 
📒 repository
  📂 docs
    📄 antora.yml
    📂 modules
      📂 gear (1)
        📂 images
          📄 image-source-file.ext
      📂 la-garita (2)
        📂 pages
          📄 page-source-file.adoc
      📂 ROOT (3)
        📂 pages
          📄 page-source-file.adoc
        📄 nav.adoc
      📂 sdk (4)
        📂 examples
          📄 example-source-file.ext
        📂 pages
          📄 page-source-file.adoc
        📄 nav.adoc
1 模块目录名为 gear
2 模块目录名为 la-garita
3 ROOT 模块目录
4 模块目录名为 sdk

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