符号链接
尽管 Antora 要求文件遵循标准层次结构，但是可以使用符号链接将现有位置上的文件重新映射到该层次结构中。本页介绍了符号链接，并解释了如何在 Antora 中使用符号链接来帮助构建内容层次结构。
什么是符号链接
符号链接是符号链接的缩写，它是一个文件的快捷方式，它本身的行为就像一个文件。换句话说，它是一个指向另一个文件的文件。符号链接的目的是为文件提供第二个位置，而不必复制它。符号链接也可以指向一个目录，它有效地将该目录下的所有文件链接到新的位置。一个符号链接甚至可以指向另一个符号链接，从而可以为文件或目录提供更多的位置。
符号链接的作用就像一个普通的文件或目录，尽管有一些额外的元数据。像 Antora 这样遇到符号链接的应用程序会像对待其他文件或目录一样对待它。此属性使符号链接成为将文件(如示例和部分)重新映射到 Antora 层次结构中的理想工具。在讨论这个问题之前，让我们先看看在什么地方支持符号链接，以及如何创建它们。
哪里支持符号链接
虽然符号链接曾经只在 Unix 和类 Unix (*nix) 操作系统中常见，但在现代计算中，对符号链接的支持是通用的。符号链接可以在本地文件系统和 git 存储库中使用，它们可以透明地在两者之间进行转换。
如果你想知道的话，符号链接也可以在 Windows 上工作。自 Windows 10 以来，Windows 完全支持符号链接(而不是一些模仿)。请参阅 Windows 10中的符号链接 以了解此功能的首次亮相。
- NOTE
-
git 中的符号链接实际上不同于操作系统文件系统中的符号链接。在 git 中，符号链接是一个数据文件(具有特殊的文件模式)，它存储对存储库中相对路径的引用。当你签出包含符号链接的分支到工作树(例如，
git clone或git checkout)时，该引用将被转换为本地文件系统上的符号链接。但即使这不会发生(core.symlinks没有启用)， symlink 将被创建为包含路径引用的常规文件(就像它在 git 存储库中一样)。
我怎么做一个符号链接
符号链接可以指向文件、目录，甚至是另一个符号链接。
在创建符号链接时，关系应该始终表示为相对路径。如果使用绝对路径，它会将符号链接绑定到本地文件系统的布局，而不会转换为 git 。
用于创建符号链接的命令取决于您使用的是类 unix 操作系统还是 Windows 。然而，它产生的结果是相同的。
*nix
要在类 unix 操作系统(又名 *nix )上创建符号链接，可以使用带 -s 标志的 ln 命令。下面是如何创建到相邻文件的符号链接的示例：
ln -s target.adoc link.adoc在这个场景中，link.adoc 是指向(即指向)文件 target.adoc 的符号链接。
这也适用于目录(又名文件夹)
ln -s target link在这个场景中，link 是指向(即指向)目录目标的符号链接。符号链接充当目录。
更常见的情况是，您希望映射到当前目录之外的位置。这意味着在符号链接目标的路径中包含一个或多个目录段。
要对目录中的文件创建符号链接，请首先导航到要创建符号链接的目录。然后，将目标指定为该目录的相对路径。这将向后看，但它将创建一个从链接开始并指向目标的指针。
ln -s ../../path/to/target.adoc link.adoc在这种情况下，link.adoc 是（即指向）文件 ../../../../path/to/target.adoc 相对于包含符号链接的目录的符号链接。目标可以在嵌套目录中而不是父目录中。
您可以对目录执行相同的操作：
ln -s ../../path/to/target link在这种情况下，link 是（即指向）目录 ../../../path/to/target 相对于包含符号链接的目录的符号链接。符号链接充当目录。
Windows
要在 Windows 上创建符号链接，可以使用 mklink 命令。下面是如何使用 mklink 创建到相邻文件的符号链接的示例：
mklink target.adoc link.adoc在这个场景中，link.adoc 是指向(即指向)文件 target.adoc 的符号链接。
要创建文件夹符号链接，必须添加 /d 参数。
mklink /d target link在这个场景中，link 是指向(即指向)目录目标的符号链接。符号链接充当目录。
更常见的情况是，您希望映射到当前目录之外的位置。这意味着在符号链接目标的路径中包含一个或多个目录段。
要对目录中的文件创建符号链接，请首先导航到要创建符号链接的目录。然后，将目标指定为该目录的相对路径。这将向后看，但它将创建一个从链接开始并指向目标的指针。
mklink ..\..\path\to\target.adoc link.adoc在这个场景中，link.adoc 是指向(即指向)文件 ..\. \path\to\target 的符号链接。相对于包含符号链接的目录。目标可以在嵌套目录中，而不是在父目录中。
您可以对目录执行相同的操作：
mklink /d ..\..\path\to\target link在这个场景中，link 是指向目录 ..\..\path\to\target 的符号链接。相对于包含符号链接的目录。符号链接充当目录。
Antora中符号链接
Antora 完全支持符号链接。这意味着你可以在工作树中使用符号链接，也可以在 git 树中使用符号链接。(是的，git也支持符号链接)。
它是如何工作的
当 Antora 遇到指向文件的符号链接时，它不会尝试将其保留为符号链接。相反，它创建一个常规的虚拟文件，就像它遇到的任何其他文件一样。我们可以说，在 Antora 的虚拟文件系统中，文件是复制的，尽管如果它是 Antora 层次结构下符号链接的唯一部分，它可能最终成为唯一的实例。
当 Antora 遇到指向某个目录的符号链接时，它会读取目标目录下的所有文件，并为每个文件创建一个常规的虚拟文件。在这种情况下，Antora 保留符号链接的路径，然后从该点向文件追加路径。就 Antora 而言，文件位于由符号链接表示的目录中，就好像符号链接是一个真正的目录一样。我们可以说，在 Antora 的虚拟文件系统中，该目录下的所有文件都是复制的，尽管如果目标目录不是其中的一部分，它们可能最终成为这些文件的唯一实例
这里的要点是，通过使用符号链接，您可以说服 Antora 文件或目录位于与实际位置不同的位置。如果它是一个指向文件的符号链接，那么 Antora 将其视为您将文件复制到那里，除非您没有。如果它是指向目录的符号链接，那么 Antora 将其视为您将目录递归地复制到那里，除非您没有。
让我们学习一下如何使用这个功能。
使用符号链接重新映射文件
让我们考虑一下符号链接特性在 Antora 中最常见的用途之一。您希望在文档中包含一些示例文件，但是这些文件不在标准的 Antora 目录结构中。为了使它们对 Antora 可用，您需要将它们重新映射到 Antora 层次结构中。
让我们来看看这个布局：
📒 docs
📄 antora.yml
📂 modules
📂 ROOT
📂 pagesAlian
📄 index.adoc
📄 nav.adoc
📒 src
📒 main
📒 java
📒 org
📒 demo
📄 MyClass.java我们要做的是将源文件 MyClass.java (或它的一部分)包含在页面 index.adoc 中。但是，由于源文件不在 Antora 层次结构下，因此目前不可能这样做。可以使用符号链接！
首先在 ROOT 模块下创建示例文件夹，符号链接将驻留在该文件夹中。
📒 docs
📄 antora.yml
📂 modules
📂 ROOT
📂 examples
📂 pagesAlian
📄 index.adoc
📄 nav.adoc
📒 src
📒 main
📒 java
📒 org
📒 demo
📄 MyClass.java接下来，让我们创建一个从 examples 文件夹到 MyClass.java 的符号链接，将其拉入 Antora 层次结构中。首先切换到终端中的该目录。
cd docs/modules/ROOT/examples然后，使用适合您的操作系统的命令创建符号链接。
ln -s MyClass.java ../../../src/main/java/org/demo/MyClass.javamklink MyClass.java ..\..\..\src\main\java\org\example\MyClass.java这是结果：
📒 docs
📄 antora.yml
📂 modules
📂 ROOT
📂 examples
🔗 MyClass.java (1)
📂 pagesAlian
📄 index.adoc
📄 nav.adoc
📒 src
📒 main
📒 java
📒 org
📒 demo
📄 MyClass.java| 1 | MyClass.java 是 src/main/java/org/example 下的 MyClass.java 文件的符号链接
|
现在可以将源文件包含在索引中。使用下面的 include 指令来创建 index.adoc 页面：
include::example$MyClass.java[]您可能会发现必须为每个想要包含的文件创建符号链接非常繁琐。这就是目录符号链接发挥作用的地方。您可以创建指向目录的符号链接，从而有效地将该层次结构嫁接到 Antora 层次结构中。
我们不创建指向源文件的符号链接目录，而是创建指向 src 文件夹的符号链接。同样，从切换到 examples 目录开始。
cd docs/modules/ROOT/examples然后，使用适合您的操作系统的命令创建符号链接。
ln -s src ../../../src mklink src ..\..\..\src这是结果：
📒 docs
📄 antora.yml
📂 modules
📂 ROOT
📂 examples
🔗 src (1)
📂 pagesAlian
📄 index.adoc
📄 nav.adoc
📒 src
📒 main
📒 java
📒 org
📒 demo
📄 MyClass.java| 1 | SRC是项目/存储库根的 SRC 文件夹的符号链接
|
现在可以将源文件包含在索引中。使用下面的 include 指令来创建 index.adoc 页面：
Unresolved include directive in modules/ROOT/pages/setUpContentSources/symlinks.adoc - include::example$src/main/java/MyClass.java[]您可以为任何类型的资源创建符号链接，包括示例、部分、页面、图像等等。虽然符号链接的目标通常在 Antora 层次结构之外，但如果要复制文件或目录，符号链接可以指向 Antora 层次结构中的位置。
局限性
在 Antora 中使用符号链接时需要注意一些限制。
-
符号链接的目标必须存在。如果 Antora 不能解析符号链接，它将抛出一个错误。
-
符号链接不能指向自身。如果 Antora 检测到这种情况，它将抛出一个错误。
-
git 存储库中的符号链接不能指向 git 存储库之外的位置。
-
git 存储库中的符号链接不能指向 git 存储库中另一个引用中的位置。
-
符号链接的目标应该是相对的。创建以绝对路径为目标的符号链接具有未定义或不可移植的行为。
不要将文档站点中未使用的大量文件映射到 Antora 层次结构中。这样做会为 Antora 增加额外的处理，从而降低构建速度。在将哪些文件映射到 Antora 层次结构中时，要尽可能精确地操作。