我注意到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!
经过一番调查后，我认为这似乎是一个错误，但仅仅是因为它有点违反直觉。
考虑以下：
The Main Section {#the_main_section}
================
Subsection One {#first}
--------------
Something highly interesting...
该文档以1级标题开头（如here所述），因此Doxygen将“主要部分”解析为页面的名称和标题。标题转换为页面名称后，标题和标签{#the_main_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!
版本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]标记放在页面标题定义下方，以将其从内容表中删除。
我正在使用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主页工作正常。出现所有标题和引用工作。希望能帮助到你！ =）
我无法控制Doxygen中Markdown页面的标题;我最终使用了实际的Doxygen @page命令：
@page pageLabel这是我的页面标题
这允许我使用@ref pageLabel引用页面，在我的Pages部分中它显示为“这是我的页面标题”。
这对我来说特别有用，因为我希望我的标题有空格，Doxygen使用文件名作为标题是不可能的。