Question

我发现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!

Answer 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!

Answer 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]标记放在页面标题定义的下方，以将其从内容表中删除。

Answer 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主页可以正常工作。出现所有标题，引用正常工作。希望能帮助到你！ =）

Answer 4

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

@page pageLabel这是我页面的标题

这使我可以使用@ref pageLabel来引用页面，并且在“页面”部分中，该页面显示为“这是页面的标题”。

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

doxygen markdown页面中的标题标签使标题标题消失

4 个答案: