如何在 doxygen 中的降价文档之间链接？答案

【问题标题】：How do I link between markdown documents in doxygen?如何在 doxygen 中的降价文档之间链接？
【发布时间】：2013-10-17 00:57:12
【问题描述】：

我有一个项目，其中包含一组降价页面，这些页面与链接相互链接，例如

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

所有页面都被 doxygen 拾取并出现在输出中，但链接并未更改为指向新的 html 再现。

我可以将链接更改为指向 html 页面，但我的项目托管在 github 上，然后这些链接会损坏，因为 github 支持自动链接 markdown 页面。

除了外部链接之外，我在 doxygen 文档中看不到任何关于支持链接的内容。有什么方法可以让 doxygen 从 markdown 生成 HTML 链接？

【问题讨论】：

doxygen 命令 \ref 有帮助吗？它适用于链接到其他降价页面中的 doxygen \section 标题，但我不确定这是否有助于您对 github 的特定要求。

标签： documentation markdown doxygen

【解决方案1】：

根据 Doxygen 1.8.7，有三种方法可以做到这一点：

使用原始问题中所述的标准降价超链接。
使用@ref 并在目标前面加上md_ 以及任何子目录。
为页面命名并使用@ref 引用该名称。

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

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

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

[Go to this page](@ref md_subdir_MyOtherPage)

显然这也是the way prescribed by the Doxygen's primary author。

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

在MyOtherPage.md 中有这个作为标题

# My Other Page Title {#MyOtherPageName}

然后像这样链接它

[Go to this page](@ref MyOtherPageName)

【讨论】：

请注意，doxygen 1.8.7 很重要，Centos 7 仍然带有 1.8.5，其中第三个选项不起作用。才三年多，最好保持doxygen稳定。

【解决方案2】：

从 Doxygen 1.8.6 开始处理常规旧 Markdown 链接，例如[link text](docs/page.md)。不过，这有点奇怪——URL 必须与 Doxygen 工作目录相对（即不是 Doxyfile 或 .md 文件的目录，而是运行 Doxygen 的目录）。如果您注意到单击链接显示的是原始 Markdown 而不是呈现的 HTML，这意味着您的 URL 与 Doxygen 的工作目录无关。

【讨论】：

这解决了我的问题，在我的情况下，我有带有 doxyfile 和 markdown 文件夹的文件夹 doc。因此我必须写[file](markdown/file.md)。谢谢！
如果我没记错的话，尝试从另一个与 Doxygen 运行位置无关的 .md 文件中引用 [some](link/to/file.md) 会破坏 Gitlab 的一切（但不是用于 Doxygen）。因此，这与同时在可查看的 repo 和 Doxygen 中具有相同的 md 文件链接从根本上不兼容。

【解决方案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)

【讨论】：

我用的是1.8.7，还是不行。它总是指 .md 文件的来源（在 html 中），而不是呈现的 (html) 页面。我使用@ref 还是[here](documentation.md) 都没有关系。有解决办法吗？
让它在 1.8.11 中工作。可能的陷阱：链接页面必须包含在INPUT中，并且链接页面不得包含标题标签（例如# Page {#page}）

【解决方案4】：

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

将STRIP_FROM_PATH 设置为 Doxyfile 目录。链接 markdown 文件时出现相对路径问题。
在 doxygen 源文件 src/docparser.cpp 的 2438 行号处附加以下代码，其中包含代码 pd = Doxygen::pageSDict->find(target);（如果它还没有）。它修复了在页面列表中搜索的降价文件。

if(pd == 0 && lang == SrcLangExt_Markdown) {pd = Doxygen::pageSDict->find(markdownFileNameToId(target));}
最后编译doxygen再试一次。

它对我有用。

【讨论】：