Repository navigation
Use appropriate heading levels in docblocks #89309
Description
Activity
Cool. I'm still around if I can be of assistance.
Interesting. Thank you for the detailed description of the issue.
I'd like to give this a shot in the upcoming week, assuming that time-frame is good and nobody's already claimed it :)
That time frame is good, and nobody's claimed this. Thanks for working on it! Feel free to ask questions if you run into any problems.
Reacted by mukundIf you want to try this out, this should now be fixed in the nightly docs. For example, here's the
Readtrait:Well done @yaymukund, thank you! @ahicks92 if you have time I'd love your input on whether this fixes the issue and whether there are still things to be improved.
It's better, and I think this is sufficient. But I'll throw out two oddities:
- The first heading on the page is h2, and reads almost identical to the h1 heading (put another way it's not immediately clear that you're in a table of contents); and
- We have jumps in the heading level, e.g. "Required methods" is h2, then
fn read(&mut self, buf: &mut [u8]) -> Result<usize>is h4.
I'm calling them oddities and not bugs/blockers because in practice this is probably at the 95th percentile when it comes to me trying to think of sites that don't get this wrong and do it well, and I'd expect anyone to be able to work it out after a bit. But it might still be worth smoothing out at some point anyway if someone ends up with the time.
Reacted by Jacob Hoffman-Andrews and mukund
Following up on #87059 (big thanks @ahicks92 for the detailed feedback!):
Here's what's happening: in Markdown
#generally represents anh1,##representsh2, and so on. That means each docblock often hash1s andh2s in them, even though they are nested under higher-uph1s andh2s. For instance, https://doc.rust-lang.org/1.55.0/std/io/trait.Read.html has an<h1>Trait std::io::Read</h1>and an<h1>Examples</h1>. The latter should be<h2>. Similarly, there's an<h4>fn read...</h4>, with an<h1>Errors</h1>nested under it. The latter should be<h5>.Per https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements#usage_notes:
Fortunately, we already control the
<h{level}>tag that's emitted based on Markdown. The code is here:rust/src/librustdoc/html/markdown.rs
Lines 535 to 540 in 2b6ed3b
<h1>or under an<h4>?{level}interpolation to add the number of levels appropriate. This should be capped at 6, since h6 is the highest defined in HTML.