option to include card/grid headers in toc tree

[story645]

Context

Hi, over at Matplotlib we maybe overly use cards and grids to organize information, e.g. landing page, contribute page and it's awesome except it makes the right hand navigation panel very sparse.

Proposal

Would it be feasible to add a directive that could tell sphinx to parse the title into a heading level that can then be included in a toctree? something like :toctree-level:? Or a css class variable sd-toctree-level-{}?

Tasks and updates

No response

[welcome[bot]]

Thanks for opening your first issue here! Engagement like this is essential for open source projects! :hugs:
If you haven't done so already, check out EBP's Code of Conduct. Also, please try to follow the issue template as it helps other community members to contribute more effectively.
If your issue is a feature request, others may react to it, to raise its prominence (see Feature Voting).
Welcome to the EBP community! :tada:

[ferdnyc]

Would it be feasible to add a directive that could tell sphinx to parse the title into a heading level that can then be included in a toctree? something like :toctree-level:? Or a css class variable sd-toctree-level-{}?

I'd say that sphinx-design should emulate Bootstrap on this point... Bootstrap cards have a Title that's automatically parsed into an <h5> element. sphinx-design encloses the titles in a <div class="sd-card-title"> instead.

That violates the web-accessibility precept that headings should be in heading elements, not merely container elements styled to look like headings, so that screen readers and other assistive technologies can find them.

...However, it's also worth noting that this change wouldn't actually help matplotlib's documentation, because it doesn't use card titles. Its card "headings" are stuffed into the header of the card, which is not typically a heading element, semantically.

A card with a header and title, from the sphinx-design docs

.. card:: Card Title

    Header
    ^^^
    Card content
    +++
    Footer

Resulting HTML

<div class="sd-card sd-sphinx-override sd-w-100 sd-shadow-sm docutils">
<div class="sd-card-header docutils">
<p class="sd-card-text">Header</p>
</div>
<div class="sd-card-body docutils">
<div class="sd-card-title sd-font-weight-bold docutils">
Card Title</div>
<p class="sd-card-text">Card content</p>
</div>
<div class="sd-card-footer docutils">
<p class="sd-card-text">Footer</p>
</div>
</div>

This part:

<div class="sd-card-title sd-font-weight-bold docutils">
Card Title</div>

Should according to WebAIM, be:

<h5 class="sd-card-title docutils">Card Title</h5>

Matplotlib documentation grid-item-card, from its docs

.. grid-item-card::
    :padding: 2
    :columns: 6

    **How to use Matplotlib?**
    ^^^
    .. toctree::
        :maxdepth: 1

        users/explain/quick_start
        User guide <users/index.rst>
        tutorials/index.rst
        users/faq.rst

Resulting HTML

<div class="sd-card sd-sphinx-override sd-w-100 sd-shadow-sm docutils">
<div class="sd-card-header docutils">
<p class="sd-card-text"><strong>How to use Matplotlib?</strong></p>
</div>
<div class="sd-card-body docutils">
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="users/explain/quick_start.html">Quick start guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="users/index.html">User guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="tutorials/index.html">Tutorials</a></li>
<li class="toctree-l1"><a class="reference internal" href="users/faq.html">Frequently Asked Questions</a></li>
</ul>
</div>
</div>
</div>

There's no <div class="sd-card-title"> to fix.