doxygen 降价页面中的标题标签使标题标题消失答案

【问题标题】：header label in doxygen markdown page makes header title disappeardoxygen 降价页面中的标题标签使标题标题消失
【发布时间】：2012-11-18 20:17:20
【问题描述】：

我注意到 doxygen 1.8.2 存在一个奇怪的问题。包含标题标签会导致标题标题从输出 html 中消失。

使用以下markdown文件：

Title            {#title}
=====

Section 1        {#section1}
---------
Text for section 1

我得到的输出为：

标题

第 1 节的文字

但是，如果我从 markdown 文件中删除 {#section1} 标签，我会得到正确的输出：

标题

第 1 节

第 1 节的文字

我在这里犯了什么错误？

编辑我在标记一个部分时观察到以下警告：

 warning: found subsection command outside of section context!

【问题讨论】：

我无法在使用 Doxygen 1.8.2 默认生成的配置文件的简单测试用例中重现此行为。您是在独立的测试用例中还是在更大的文档集中看到这种行为？您可能需要发布您正在使用的文件的确切内容，包括配置文件。
与 1.8.8 相同的“问题”。我有一个 README.md，它做了完全相同的事情，但没有最顶层标题的标签。

标签： markdown doxygen

【解决方案1】：

经过一番调查，我认为这似乎是一个错误，但这只是因为它有点违反直觉。

考虑以下几点：

The Main Section {#the_main_section}
================

Subsection One {#first}
--------------

Something highly interesting...

文档以 1 级标题开始（如 here 所述），因此 Doxygen 将“主要部分”解析为页面的名称和标题。将标题转换为页面名称后，标题和标签{#the_main_section} 似乎将被忽略。

然后处理移动到文档的其余部分，当它到达“Subsection One”时，它认为“subsection”没有父“Section”（因为“Section”已转换为页面名称) 这就是令人窒息的地方。

更具体地说，它会丢弃子节（标题），因为它认为没有父“节”。所有其他文本仍然存在，但被视为“页面”的一部分（没有部分父级）。

“修复”是在初始“1 级标题”之后添加另一个“1 级标题”，例如

My Great Documentation (Which Becomes the Page Name)
====================================================

The First Section
=================

Q. What? I already created a level 1 heading?
A. Yup, but that was converted to a page name/title and discarded, so now
   we have to create another level 1 heading for my first section. Don't
   be fooled into thinking that the opening heading in this document is
   still treated as an opening heading by Doxygen - it's not!

【讨论】：

我应该补充一点，这仍然不能解释（我也不清楚）为什么删除标签会使 Markdown 的外观正常工作。我说“给外观”，因为如果您删除标签并尝试在文档中添加[TOC]，则不会产生 TOC！如果您实施上述“解决方法”，则解析后的文档会显示正确并且包括带有指向节/小节标题的链接的 TOC。
这是一个讨论这些问题的页面（包括您评论中的问题）：svenax.net/site/2013/07/…。唯一没有提到的是，不标记包括最上面的标题（页面名称除外）在内的所有部分会导致它们根本不显示，不仅在 TOC 中，而且在页面本身上。
Google 员工注意： 现在是 2015 年，doxygen 1.8.9.1 仍然存在这个错误！感谢莱斯特的解决方案:)
我使用的是 doxygen 1.8.11，我相信它正确处理了页面名称 TOC。
@Phil 似乎没有...错误/问题在 1.8.13 版中仍然存在

【解决方案2】：

版本 1.8.9.1 中的相同问题。您可以通过使用 # 标签而不是 --- 来避免它。

例如：

[TOC]

Page Title {#pageTitle}
==========
Lorem ipsum dolor sit amet

# section 1 {#section1}
Lorem ipsum dolor sit amet

## Section 1.1 {#section1-1}
Lorem ipsum dolor sit amet

# section 2 {#section2}
Lorem ipsum dolor sit amet

# section 3 {#section3}
Lorem ipsum dolor sit amet

## section 3.1 {#section3-1}
Lorem ipsum dolor sit amet

# section 4 {#section4}
Lorem ipsum dolor sit amet

会起作用。您甚至可以将 [TOC] 标签放在页面标题定义下方，以将其从目录中删除。

【讨论】：

我在 1.8.15 中尝试使用 [TOC] - 但是虽然我可以让 TOC 出现，但标题本身却消失了（根据 OP）。

【解决方案3】：

我使用的是 Doxygen 1.8.14，我遇到了同样的问题。我想分享一下我是如何解决的。

正如http://svenax.net/site/2013/07/creating-user-documentation-with-doxygen/ 中所建议的那样我设置了 USE_MDFILE_AS_MAINPAGE = mainpage.md，并确保标记所有部分和子部分。

正如 Lester Burnham 所说，该文档需要两个 1 级标题。但是，要使其第一个使用“=========”样式，第二个使用“#”样式。像这样：

My main page    {#mainpage}
============


# Introduction  {#intro}
Text.....


## A sub section    {#subsection1}
Text... and a reference to the [Introduction](#intro).

有了这个，我的 Doxygen 主页运行良好。出现所有标题并且参考工作。希望能帮助到你！ =)

【讨论】：

【解决方案4】：

我无法在 Doxygen 中控制我的 Markdown 页面的标题；我最终使用了实际的 Doxygen @page 命令：

@page pageLabel 这是我的页面标题

这允许我使用@ref pageLabel 引用页面，并且在我的页面部分中它显示为“这是我的页面的标题”。

这对我特别有用，因为我希望我的标题有空格，而 Doxygen 无法使用文件名作为标题。

【讨论】：