我该如何在Doxygen中链接Markdown文档？

Question

我有一个项目，其中包含一组互相链接的Markdown页面，链接形式如下：

[Go to this page](subdir/MyOtherPage.md)

这些页面都被Doxygen捕获并出现在输出中，但链接没有改变以指向它们的新HTML版本。

我可以更改链接以指向HTML页面，但我的项目托管在GitHub上，那么这些链接将会变成损坏的，因为GitHub支持自动在Markdown页面之间进行链接。

我在Doxygen文档中没有看到除了外部链接之外的其他链接支持。 有没有办法使Doxygen从Markdown文件中生成HTML链接？

- izb

---

doxygen 命令 \ref 有帮助吗？它对我来说可以用于链接到其他 markdown 页面中的 doxygen \section 标题，但我不确定它是否有助于满足您在 github 上的特定要求。 - Cheeseminer

Answer 1

根据Doxygen 1.8.7的说明，有三种方法可以实现这一点：

• 使用标准的Markdown超链接，就像你原来的问题描述的那样。
• 使用@ref并在目标前缀中添加md_以及任何子目录。
• 命名页面并使用@ref引用该名称。

第一种方法很简单，而且在没有使用Doxygen的情况下也可以工作（例如在Github上浏览代码库时）。

[Go to this page](subdir/MyOtherPage.md)

而第二种方法您需要像这样链接它：

[Go to this page](@ref md_subdir_MyOtherPage)

显然这也是Doxygen的主要作者所建议的方式。

最后，在第三种方法中，您需要为目标页面命名，然后链接到该名称。例如：

在MyOtherPage.md中将其设置为标题。

# My Other Page Title {#MyOtherPageName}

然后像这样链接它

[Go to this page](@ref MyOtherPageName)

- adib

---

请注意，doxygen 1.8.7 版本非常重要，Centos 7 自带的版本是 1.8.5，第三个选项将无法使用。已经过去三年了，最好保持 doxygen 的稳定性。 - ted

连接到单独页面的第一种和第二种方法会导致在输出页面中出现 @ref md_subdir_MyOtherPage "转到此页面"（字面上，浏览器会这样显示；没有生成超链接）。如果链接指向另一页，则与前两种方法相同的问题也会出现。当我链接到同一页上的某个部分时，第三种方法可以很好地工作（链接也可以排版为[转到此页面](#MyOtherPageName)）。 - Ruslan

使用Doxygen 1.9.1/1.9.7时，前两种方法对我来说无效，但第三种方法运行良好。 - Werner Henze

Answer 2

自Doxygen 1.8.6起，可以处理普通的Markdown链接，例如：[链接文本](docs/page.md)。但是它的工作方式有点奇怪——URL必须相对于Doxygen的工作目录（即不是Doxyfile或.md文件的目录，而是从Doxygen运行的目录）。如果您发现单击链接显示原始Markdown而不是呈现的HTML，则表示您的URL不是相对于Doxygen的工作目录。

- kyrofa

---

这对我解决了问题，我的情况是我有一个名为doc的文件夹，里面有doxyfile和markdown文件夹。因此，我必须写成[file](markdown/file.md)。谢谢！ - Javi

如果我没记错的话，试图从另一个与Doxygen运行位置无关的.md文件引用some会导致Gitlab中所有内容都崩溃（但Doxygen不会）。因此，在repo中同时查看md文件和Doxygen具有相同的链接是根本不兼容的。 - Germán Diago

Answer 3

此功能是在Doxygen 1.8.6（2013年12月）中添加的。

Allow @ref to unlabeled markdown page by name, i.e. @ref mypage.md
Allow links to other markdown pages of the form [link text](page.md)

为了使其正常工作，您可能需要在链接中包含文档目录，例如

[link text](docs/page.md)

- rockgecko

---

我使用1.8.7，但它仍然无法正常工作。它总是引用.md文件的源代码（在HTML中），而不是渲染后的（HTML）页面。无论我使用@ref还是[here](documentation.md)都没有影响。有没有解决方法？ - verpfeilt

在1.8.11中已经解决了。可能会遇到的问题是：链接页面必须包含在INPUT中，并且链接页面不能包含标题标签（例如# Page {#page}）。 - Conrado

Answer 4

以下步骤可能会解决问题，

• 将STRIP_FROM_PATH设置为Doxyfile目录。在链接markdown文件时存在相对路径问题。

• 在doxygen源文件src/docparser.cpp的2438行代码中添加以下代码，其中包含代码pd = Doxygen::pageSDict->find(target);（如果尚未存在）。它修复了页面列表中搜索markdown文件的问题。

  if(pd == 0 && lang == SrcLangExt_Markdown) {pd = Doxygen::pageSDict->find(markdownFileNameToId(target));}

• 最后编译doxygen并重试。

我用这个方法解决了我的问题。

- KRoy