MkDocs:使用变量构造外部URL

Question

使用AsciiDoc，我可以定义一个基本URL属性并引用它来定义链接：

:external-url: https://www.example.com/docs

:Foo: {external-url}/foo[Foo,role=external-doc]
:Bar: {external-url}/bar[Bar,role=external-doc]
:Baz: {external-url}/baz[Baz,role=external-doc]

然后，我可以使用{Foo}语法将链接注入文档页面。

用MkDocs实现这一目标的最佳方法是什么？如果可能的话，我想避免复制基本URL。

Answer 1

MkDocs正在使用Markdown，因此没有现成的变量可供使用.因此，您需要使用一些东西来预处理您的标记文件。

你应该做两件事：

1. 哪个预处理程序使用
2. 如何集成到您的处理中.

对于第一个问题，我的回答是Jamal，可以从https://github.com/verhas/jamal获得

我创建Jamal是为了解决这样的问题，并将可编程语义信息包含到您的文档中。你应该接受这个建议，因为贾马尔是我最爱的孩子，所以我创造了它。

另一个问题是如何将其集成到Mkdocs中。在这里我看到了三种不同的可能性：

1. 使用预处理器手动维护.md.jam文件，并在构建文档站点之前将它们转换为.md文件。这是最直接的方法，因为它只需要在开始构建之前执行命令。但是，另一方面，最容易忘记这样做，最终会有过时的标记文件。

。

您可以使用ANT、make或其他构建工具来修补此解决方案。

1. 创建一个MkDocs插件，该插件启动转换并将所有md.jam文件转换为.md文件。您需要编写一个简短的Python模块，该模块作为外部进程启动Jamal。它需要一些Python编程，但是它的优点是您不会忘记执行Jamal处理，因为所有的构建都会为您完成这个任务。

这两种方法都有这样的优点，您可以摆脱引入的Jamal处理。可以在源结构中创建.md文件。如果您决定，您可以删除Jamal文件并继续直接编辑Markdown文件，从而承担维护冗余信息的文档源的所有后果。

1. 最后，您可以开发一个Python插件来处理.md文件中的Jamal宏。因为Jamal是用Java编写的，所以这个插件必须执行外部进程。在我看来，这可能是最复杂的方法，也是最不实际的方法。在这种情况下，您的Markdown文件包含Jamal宏，并且您的源代码集中没有转换的、没有宏的Markdown文件。这些东西多次派上用场。插件对每个Markdown文件分别作为单独的进程启动Jamal，而前面的方法可以在单个进程中转换所有文件。

我建议的是

看看Jamal的特性，如果您喜欢它，并了解这是否真的是您需要的--开始使用它作为一个单独的预处理程序--当您真的需要它时，您可以考虑编写一个MkDocs插件来自动执行转换。