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?

Chenay

Answer 1

@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).

Punic

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. – Punic

I haven’t lost interest. I am working on something else ATM and haven’t had an opportunity to revisit this. – Chenay

Answer 2

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;
}

Domenech

Answer 3

The maxdepth option indicates the wanted depth of the TOC.

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

Observance

That's a temp workaround, not a proper solution, since now I cannot display sub-toctrees if I want to. – Chenay

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. – Observance

I have just re-edited my original post to clarify what I am asking. Hope that makes it easier to understand. – Chenay

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. – Observance