19

I notice a strange problem with doxygen 1.8.2. Including a header label causes the header title to disappear from the output html.

With the following markdown file:

Title            {#title}
=====

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

I get the output as:

Title

Text for section 1

But, if I remove the {#section1} label from the markdown file, I get the correct output as:

Title

Section 1

Text for section 1

What is the mistake I am making here?

Edit I observed the following warning when I label a section:

 warning: found subsection command outside of section context!
Masked Man
  • 1
  • 7
  • 40
  • 80
  • I was unable to reproduce this behavior in a simple test case with a default generated configuration file for Doxygen 1.8.2. Do you see this behavior in a stand alone test case or as a part of a larger document set? You may need to post the exact content of the files you are working with, including the configuration file. – DRH Dec 09 '12 at 07:07
  • Same "problem" with 1.8.8. I had a README.md that did the exact same thing, but without the label for the topmost header. – Mad Physicist Sep 18 '14 at 18:41

4 Answers4

28

After some investigation, I have decided this appears to be a bug, but only because it is slightly counter-intuitive.

Consider the following:

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

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

Something highly interesting...

The document starts with a level 1 header (as described here) and so Doxygen parses "The Main Section" as the name and title of the page. The header and the label {#the_main_section} appear to be disregarded once the header has been converted into a page name.

The processing then moves on to the rest of the document and When it reaches "Subsection One", it believes that there is no parent "Section" for the "subsection" (as the "Section" was converted to a page name) and this is where it chokes.

More specifically, it discards the subsection (header) as it believes there is no parent "section". All other text remains, but is treated as part of the "page" (with no section parent).

The "fix" is to add another "level 1 header" after the initial "level 1 header" e.g.

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!
albert
  • 8,285
  • 3
  • 19
  • 32
PeterByte
  • 3,534
  • 2
  • 20
  • 16
  • 3
    I should add that this still does not explain (nor is it clear to me) why removing the labels gives the appearance of the Markdown working correctly. I say "gives the appearance", because if you remove the labels and try to add a `[TOC]` to the document, no TOC is produced! If you implement the "workaround" described above, then the parsed document appears correct **and** includes the TOC with links to the section/subsection headings. – PeterByte Dec 19 '12 at 15:11
  • Here is a page that discusses these issues (including the one from your comment): http://svenax.net/site/2013/07/creating-user-documentation-with-doxygen/. The only thing that is not mentioned is that not labelling ALL of the sections including the topmost header (except the page name) causes none of them to show up at all, not just in the TOC, but on the page itself. – Mad Physicist Sep 18 '14 at 18:58
  • 1
    **Note to Googlers:** It's 2015 and doxygen 1.8.9.1 still has this bug! Thanks Lester for the solution :) –  Aug 13 '15 at 09:33
  • I am using doxygen 1.8.11 and I believe it correctly handles the page name TOC correctly. – Phil Sep 14 '16 at 17:21
  • @Phil it's seem it does not... The bug/issue is still there in version 1.8.13 – kazbeel Jul 11 '17 at 10:18
  • You're a genius and just saved me a lot of time. Version `1.8.14` here. – aremmell May 09 '18 at 20:50
  • Version 1.8.15 here, problem still exist. And for me, the problem is even worser, even if i have two level 1 titles, The warning message still exist. – H.C.Liu Jul 14 '18 at 09:55
  • This fixed the problem for me with Ubuntu 18.04 and doxygen `1.8.13`. I had added a `[TOC]` to a **different** Markdown page and suddenly all of the others had this problem. – phoenix Jan 23 '19 at 14:08
1

Same issue in the version 1.8.9.1. You can avoid it by using # tags instead of --- .

For example:

[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

will work. You can even put the [TOC] tag below the page Title definition to remove it from the table of content.

Michael
  • 11
  • 1
  • I was trying `[TOC]` with 1.8.15 - but while I could get the TOC to appear, the headings themselves vanished (as per OP). – simon.watts Apr 24 '20 at 13:44
0

I'm using Doxygen 1.8.14 and I had the same issue. I want to share how I solve it.

As suggested in http://svenax.net/site/2013/07/creating-user-documentation-with-doxygen/ I set USE_MDFILE_AS_MAINPAGE = mainpage.md, and also made sure to label all sections and subsections.

As mentioned by Lester Burnham the document needs two level 1 headers. However to make it works the first one with the "=========" style and the second with the "#" style. Like this:

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


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


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

With this my Doxygen main page is working fine. All headers appearing and the references working. Hope it helps! =)

olmanqj
  • 3
  • 3
0

I was having trouble controlling the title of my Markdown pages in Doxygen; I ended up using the actual Doxygen @page command:

@page pageLabel This is my page's title

This allows me to reference the page using @ref pageLabel, and in my Pages section it shows up as "This is my page's title".

This was especially useful for me because I want my titles to have spaces, which isn't possible of Doxygen uses the file name as the title.

mynameisjohnj
  • 421
  • 4
  • 12