Markdown table of contents depth cannot be bigger than TOC_INCLUDE_HEADINGS

[eseiler]

Describe the bug

Doxyfile: TOC_INCLUDE_HEADINGS = 2

Markdown:

# Page header

@tableofcontents{html:3}

# Header 1

## Header 2

### Header 3

#### Header 4

Will result in a TOC with a depth of 2.

Expected behavior
TOC should have a depth of 3.

To Reproduce
example.tar.gz

Version
1.9.2 (72bce7443241675a63ac53739bafa1d00cdbe372)

Stack trace
Not using [TOC] will prevent the markdown processor to replace it with @tableofcontents{html:TOC_INCLUDE_HEADINGS_VALUE}.

However,

doxygen/src/markdown.cpp

Line 1485 in 72bce74

if ((level > 0) && (level <= Config_getInt(TOC_INCLUDE_HEADINGS)))

will still check if the given depth is smaller than the value in TOC_INCLUDE_HEADINGS. Simply removing the check for <= will result in a TOC depth of 3.

I think the TOC_INCLUDE_HEADINGS should act more like a default and not restrict the TOC depth if you wish to explicitly overwrite it. Currently, you can decrease the depth, but you cannot increase it.

[albert-github]

This is not an easy problem as it has multiple components.

• the doxygen command \tableofcontents
• the markdown command [TOC]
• the usage of the markdown paragraph / subparagraph commands # / ## etc.

Further we also have to look at the treeview (at the right) when GENERATE_TREEVIEW=YES

The markdown processor does hardly know anything about the used doxygen commands (just a little about some block commands like \code) and doesn't know anything about the doxygen command \tableofcontents. When the markdown processor would know something about the \tableofcontents command it probably also has to know things commands like \page etc.

[eseiler]

Mhm, does the markdown processor need to know?
Maybe I missed the point, but the processor seems to parse [TOC]

doxygen/src/markdown.cpp

Lines 1004 to 1008 in 72bce74

	else if (content=="TOC")
	{
	isToc=TRUE;
	i=contentEnd;
	}

and replace it with the doxygen command

doxygen/src/markdown.cpp

Lines 1021 to 1030 in 72bce74

	if (isToc) // special case for [TOC]
	{
	int toc_level = Config_getInt(TOC_INCLUDE_HEADINGS);
	if (toc_level > 0 && toc_level <=5)
	{
	m_out.addStr("@tableofcontents{html:");
	m_out.addStr(QCString().setNum(toc_level));
	m_out.addStr("}");
	}
	}

If I directly put @tableofcontents{html:3} into my markdown, the processor does not change this line and just puts it into the output.

Edit:
A more accurate description of this ticket would probably be that @tableofcontents{html:3} and \tableofcontents{html:3} use TOC_INCLUDE_HEADINGS as upper limit.
If you use TOC_INCLUDE_HEADINGS to set a default depth, this prevents you from explicitly using deeper TOC's with the doxygen commands.

[albert-github]

When you would put a [TOC] on the same page ad the \tableofcontents (as a test) you would see that there would be 2 \tableofcontents present. This can easily be seen when running doxygen -d markdown

[eseiler]

When you would put a [TOC] on the same page ad the \tableofcontents (as a test) you would see that there would be 2 \tableofcontents present. This can easily be seen when running doxygen -d markdown

Yes and the output would only have one tree of contents.
If I use multiple [TOC], only the last one is parsed properly.

But I'm not sure if we are talking about the same thing:

I want to use @tableofcontents/\tableofcontents instead of [TOC], because I want to set a custom depth of the TOC for this page only.
For all other [TOC] I might have in some other markdown files, the TOC_INCLUDE_HEADINGS acts as a default, which is fine.

However, TOC_INCLUDE_HEADINGS also acts as an upper limit for the TOC depth, which means I cannot have individual pages have a deeper TOC. I can only make the TOC more shallow.

Sorry if I wasn't clear enough and/or didn't get your earlier comment about how this affects markdown parsing.

[albert-github]

I think that in the later case (at least at the moment) best is to use also the\section / \subsection etc. commands.