1

至少它显然很受欢迎，但是 mkdocs 目录中的“主”文件必须称为 index.md 吗？如果我在其他地方的文件夹中引用文档，即不属于该文件的层次结构，该怎么办？我问，因为我对其他地方链接的文件有一个小问题。我在网上找到的关于此的文档很少（如果有的话）。谢谢

4

1 回答 1

3

选择文件名“index.md”是因为它配置了多少（大多数）Web 服务器。通常，URL 有两种形式（无论如何都与此讨论相关）。它们要么指向一个目录，要么指向一个文件。

  • /path/to/a/directory/
  • /path/to/a/directory/with_a_file.html

Web 服务器通常配置的默认行为是，当它接收到对目录的请求时，它将提供该index.html目录中的文件。换句话说，当对 进行请求时/path/to/a/directory/，服务器将返回文件/path/to/a/directory/index.html。

MkDocs 没有用不同的命名约定重新发明这种行为，而是简单地借用了相同的行为。/index.md当您使用 MkdDocs “构建”您的站点时，文件/index.html位于/. 现在，您可以重新配置服务器以在请求目录时提供不同的服务，但现有系统已经存在多年，因此这样做几乎没有意义。

因此，如果您在文档中创建指向目录中页面的链接，请直接链接到该页面：/path/to/some/page.html. 但是，如果您要链接到目录中的“主”页面，请链接到目录本身：/path/to/a/directory/然后将提供该页面/path/to/a/directory/index.html。

您需要注意的唯一额外考虑因素是 MkDocs 使这变得更加容易。您不需要知道文件将被构建到哪个路径。如果您链接到 Markdown 文件，MkDocs 将做“正确的事情”并重写链接以指向所记录的构建的 HTML文件。所以链接到some/page.md，它会为你重写链接到some/page.html或some/page/，这取决于你如何use_directory_urls配置设置。请注意，当use_directory_urls设置为true（默认）时，MkDocs 使用“索引”技巧，将每个文件作为索引文件放在其自己的目录中，因此不会使用文件扩展名。但是，只要您.md在内部使用链接，就会正确生成链接。

重读您的问题后，我突然想到您可能正在尝试链接到 MkDocs 站点之外的文档。但是，尚不清楚您是指托管在同一站点上还是托管在其他站点上的文档。所以我会涵盖两者。

对于托管在其他站点上的文档，只需包括整个地址，包括主机。就我个人而言，我经常会在浏览器中打开页面，然后在地址栏中选择地址，然后将整个内容复制到我的文档中。例如，上面指向 MkdDocs 文档的链接是http://www.mkdocs.org/user-guide/writing-your-docs/#linking-documents所以我将整个内容作为链接 URL 复制到这个答案中。

如果您询问是否链接到同一主机内的其他文档，那么这取决于您的配置。例如，如果您有多个内容并排提供服务，其中您有一些文档http://example.com/foo/要从您的 MkDocs 站点链接到该站点，http://example.com/bar/那么您可以像使用外部站点一样使用完整链接，或者您可以使用相对 URL，如我对您的问题的回答中所述：Markdown：引用文档路径之外的目录（“对等”文件夹）。也许通过更好地了解“索引”页面的工作原理，您将能够更好地构建相对链接。

另一方面，如果您希望链接到文档根目录之外的文件，那么您不能。我见过的任何 Web 服务器都配置为引发错误作为安全预防措施，并且不会提供服务器根目录之外的任何文件。如果您想提供一个文件并且您无法将其从服务器根目录之外的位置删除，那么您将需要复制它，或者在文件系统中创建指向它的操作系统级链接。也就是说，取决于您的服务器的配置方式，操作系统级别的链接可能会成功，也可能不会成功。但是，这将是另一个问题的主题。

于 2016-02-25T17:13:42.520 回答