Fix hierarchy of headers a few pages in the documentation

[browniebroke]

Description

As per #9908

The page has multiple h1 tags which means the navigation only renders the first one. Looks like a number of our pages have the same problem... 😞

• Live preview: https://browniebroke-drf--4.org.readthedocs.build/en/4/

[browniebroke]

This is what makes the page ToC "integrated" under the section navigation, but this is getting very long for some pages... By removing that line, the table of content of the current page is on the right side instead. Thoughts?

Before

(with toc.integrate)

After

(without toc.integrate)

[browniebroke]

On the homepage, the navigation on the left has a single item and it looks weird. Hiding it to save some space.

[Copilot]

Pull request overview

This PR fixes a navigation rendering problem in the MkDocs documentation site caused by multiple h1 tags on several pages. Previously, with toc.integrate enabled, only the first h1 heading was used by the navigation. The fix downgrades secondary h1 headings to their proper levels throughout several documentation files, and also removes toc.integrate from the theme configuration.

Changes:

• Removed toc.integrate from mkdocs.yml and added hide: navigation to the index page frontmatter
• Demoted multiple # Section headings to ## Section (and ## subsection to ### subsection) in serializers.md to produce a single logical page root
• Removed the redundant top-level # PageTitle from requests.md, authentication.md, and content-negotiation.md, and demoted their sub-headings accordingly; retained the single # PageTitle h1 in fields.md and exceptions.md while shifting their secondary headings

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
mkdocs.yml	Removes toc.integrate feature (which caused only the first h1 to appear in navigation)
docs/index.md	Adds hide: navigation frontmatter to prevent the left nav sidebar on the homepage
docs/api-guide/serializers.md	Demotes all h1 section headings to h2 and h2 subsections to h3 throughout the file
docs/api-guide/requests.md	Removes the page-title # Requests h1 and demotes sub-headings
docs/api-guide/fields.md	Retains the single # Serializer fields h1; demotes internal # Section to ## Section and ## Item to ### Item; converts a #### Parsers and file uploads heading to a !!! note admonition
docs/api-guide/exceptions.md	Retains the single # Exceptions h1; demotes internal # API Reference etc. to h2 and ## Exception types to h3
docs/api-guide/content-negotiation.md	Removes the page-title # Content negotiation h1 and demotes sub-headings
docs/api-guide/authentication.md	Removes the page-title # Authentication h1 and demotes sub-headings

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 28 out of 28 changed files in this pull request and generated 1 comment.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[auvipy]

the API and other option do not provide any drop down menu like before. is that intended?

[browniebroke]

the API and other option do not provide any drop down menu like before. is that intended?

What do you mean by "before"? Do you mean on the old theme? Or on the updated them, before this fix?

• On the old theme, the horizontal navbar at the top, used to be dropdowns. Now the content of these dropdown is the navigation on the left side of each page. I didn't find an option in the new theme to keep the old behaviour, which I assum is because of accessibility issues (e.g. on mobile)
• Before this PR, the table of content of the current page was nested inside the left navigation, now it's on the right side of each page. This is what I describe in this comment.