Sphinx adds Headings from Markdown File to Document Structure

Question

I have configured Sphinx to use markdown files.

In my index.rst file I have

.. toctree::
   :maxdepth: 2
   :caption: Contents:

   documents/Markdown

In Markdown.md I have

# Markdown

## H2 Heading

When I render the main page I get the H2 heading appearing in the toctree.

I have other parts of my toctree where I want a :maxdepth of more than 1. Why does sphinx read the H2 heading as part of the toctree, and how can I get it to stop doing this, without having to set the the :maxdepth to 1?

score 2 · Accepted Answer · answered Mar 12 '19 at 14:18

2

@mzjn answers partially your request. Personally, I am not sure how is this exactly done in Markdown but I assume it is similar to reStructuredText. Unfortunately, at the moment there isn't an intuitive way to do this. However, you can do the following:

.. toctree::
   :maxdepth: 1

   documents/Markdown1

.. toctree::
   :maxdepth: 2

   documents/Markdown2

This will output the desired behaviour but you will have some vertical spacing between your two trees in this case. Either you do that or you can use:

.. toctree::
   :maxdepth: 2

   documents/Markdown1
   documents/Markdown2

But you will need to transfer what you don't want to be shown to a lower level (H3 for example).

answered Mar 12 '19 at 14:18

SuperKogito

2,998
3
16
37

The OP explained that he has multiple entries in his tree, for which he wants to display different depths. Using `:maxdepth:1` will limit the depth for all entries and you did not specify how can you use different depths for different tree entries. – SuperKogito Mar 12 '19 at 16:38
I haven’t lost interest. I am working on something else ATM and haven’t had an opportunity to revisit this. – Mr. J Mar 12 '19 at 21:30

score 1 · Answer 2 · answered Aug 07 '20 at 16:21

Adding on to @SuperKogito's answer. If you want your TOC to support different depth levels while still looking whole, you can do this via CSS.

For example, given the following section

Contents  # this will create a <div id="contents>...</>
========

.. toctree::
   :maxdepth: 1

   documents/Markdown1

.. toctree::
   :maxdepth: 2

   documents/Markdown2

In your conf.py, at the bottom, add the following lines

def setup(app):
    app.add_css_file('styles.css')

Now in your _static folder (which is at the same folder level as your conf.py), add a file called styles.css with the following lines

// this selects the contents section, the first table of contents and the list item
// underneath it. Then it removes the spacing to make it look whole. If you have more
// items, you can consider using :not(:last-of-type) selector. 
#contents .toctree-wrapper:first-of-type ul {
    margin-bottom: 0;
}

score -1 · Answer 3 · answered Feb 21 '19 at 06:46

-1

The maxdepth option indicates the wanted depth of the TOC.

If you use:maxdepth: 1, "H2 heading" should disappear.

answered Feb 21 '19 at 06:46

mzjn

48,958
13
128
248

That's a temp workaround, not a proper solution, since now I cannot display sub-toctrees if I want to. – Mr. J Feb 21 '19 at 23:02
Why is my answer not a proper solution? "sub-toctrees" are not mentioned in the question. You asked *"I get the H2 heading appearing in the table of contents. Why?"*, and I have explained why. – mzjn Feb 23 '19 at 09:42
I have just re-edited my original post to clarify what I am asking. Hope that makes it easier to understand. – Mr. J Feb 25 '19 at 01:18
For each `toctree` directive, there is one `maxdepth` setting. You cannot have different depths for different documents included in the same toctree. That is not how it works. The toctree you have in the question behaves as expected. – mzjn Feb 25 '19 at 05:46

Sphinx adds Headings from Markdown File to Document Structure

3 Answers3

Linked