Incorrect Headline Hierarchy in Rust Book

[killercup]

In the markdown files, a number sub-chapter headlines seem to be first level ones (single #), resulting in h1s in the output. The chapter title is rendered as a h1 as well. This is semantically wrong—the content contains subheadings to the chapter.

An example is the chapter The Rust Testing Guide. It should be noted that some chapters do use second level headlines, e.g. Compound Data Types.

Since the chapter heading is not inserted as a regular headline but as special title attribute (%), it is debatable what is the correct content headline level is.

Two possible ways to fix this:

• Change all files to contain at most second level headlines
• Change rustbook to increment headline levels by one

cc @steveklabnik

[steveklabnik]

I think this is a dup of another Rustdoc issue, but I can't find it at the moment. It should be handled at the rustdoc layer.

[tomjakubowski]

I think I know what issue you mean and it doesn't seem like a dupe of that to me. The root of that issue ultimately was that API docs are made up of doc comment blocks on individual items. Since each doc comment block compromises a whole "subdocument" of sorts, there's no way for the headings in a doc comment block to "know" which level they ought to be, because they don't know where or how they'll be inserted in a larger document (the whole API docs on a module or item or whatever).

Here, we just have long prose documents that simply need to be marked "down" correctly but aren't right now.

[killercup]

Is this actually something to be handled/added at the rustdoc layer or just a parameter that rustbook neeeds to set when calling rustdoc? (Or maybe both?)

I haven't found that issue you referred to either. I may have an idea for the API docs, though. I've opened #20863 for this. If you find that other issue, just close this new one.

[akavel]

I've created a pull request, in case moving all headings 1 level "down" in all files where there are 1st level headings is an acceptable solution to this issue. (I've done this only for The Book.)

[steveklabnik]

Triage: this still happens, but yeah, this is part of just how Markdown works, I'd say, echoing @tomjakubowski . Closing as not a bug. If we have incorrect markup generated, we should fix it in the source.