H2 and H3 headings are still too visually similar

[vivodi]

Description

While improvements have been made to differentiate H2 and H3 headings as a result of issue #97, the distinction between them remains subtle. This lack of clear visual hierarchy makes it difficult for readers to quickly discern the structure of the document, potentially hindering comprehension.

Comparison with Other Themes

For reference, other popular documentation themes provide a more pronounced difference between their H2 and H3 headings:

• Furo: The H2 headings in Furo are 33% larger than H3 headings and also have a greater top margin, creating a strong visual separation.
  • Example: Furo Documentation
• Material for MkDocs: This theme uses a 25% larger font size for H2 headings compared to H3, and further differentiates them through a noticeable change in font-weight.
  • Example: Material for MkDocs Documentation

In the PyData Sphinx Theme, the font-size of H2 headings (2.125rem) is only 21% larger than that of H3 headings (1.75rem). This minimal difference is not as effective as the visual cues in the aforementioned themes.

Proposed Solutions

To improve the scannability and structural clarity of the documentation, I suggest increasing the visual distinction between H2 and H3 headings. H2 and H3 are the most frequently used heading levels and have the greatest impact on a reader's ability to understand the document's structure.

Potential approaches include:

1. Increase Font Size Difference: Widen the gap in font-size between H2 and H3 headings.
2. Adjust Margins: Increase the margin-top of H2 headings to create more vertical space and a clearer separation from the preceding content.
3. Modify Font Weight: Use a bolder font-weight for H3 headings.
4. Implement Separators: Introduce a horizontal rule or a similar visual separator beneath each H2 section, similar to the approach taken by VitePress.
   • Example: VitePress Documentation

Relevant Code Snippets:

• PyData Sphinx Theme: _fonts.scss#L9-L16
• Furo: _typography.sass#L45-L59
• Material for MkDocs: _typeset.scss#L97-L155

A more distinct visual hierarchy between these heading levels would significantly enhance the readability and user experience of documentation generated with this theme.