Repository navigation
Conversation
✅ Deploy Preview for adk-docs-preview ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Seven pages skipped heading levels, which breaks the document outline
for screen-reader users and in-page navigation:
* agents/workflow-agents/{loop,parallel,sequential}-agents.md went
straight from the page h1 to h3, and every section on those pages is
a top-level section, so all of their h3s become h2s.
* deploy/agent-runtime/agents-cli.md had five h3 sections before an h2
("Test deployed agents"), inverting the page order.
* optimize/index.md opened with "Definitions" as an h3 before an h2.
* deploy/gke.md used h4 for "Prerequisites" under an h2.
* evaluate/criteria.md used h4 for the four sub-sections of both
"tool_trajectory_avg_score" and "per_turn_user_simulator_quality_v1"
while every other criterion uses h3.
Heading anchors are derived from heading text, not from heading level,
and the two explicit {#...} anchors on the agents-cli page are kept, so
no in-page or inbound links change. A repo-wide outline scan now reports
zero heading-level skips.
AAliKKhan
force-pushed
the
fix/heading-hierarchy-skips
branch
from
October 19, 2026 11:51
7f24817 to
baf9653
Compare
This branch has not been deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Seven pages skip heading levels. 24 headings are promoted one level so every
page follows
h1 -> h2 -> h3with no gaps.docs/agents/workflow-agents/loop-agents.md###->##docs/agents/workflow-agents/parallel-agents.md###->##docs/agents/workflow-agents/sequential-agents.md###->##docs/deploy/agent-runtime/agents-cli.md###->##docs/optimize/index.md###->##docs/deploy/gke.md####->###docs/evaluate/criteria.md####->###Why
loop/parallel/sequential-agents.md- each page goesh1thenstraight to three
h3sections. All three sections are peers and are thepage's top-level sections, so all three become
h2.agents-cli.md- fiveh3sections appear before theh2"Test deployed agents", so the outline implies the deployment steps are
subsections of a section that appears after them.
optimize/index.md- the page opens with### Definitionsfollowed by## Example.deploy/gke.md-#### Prerequisitessits directly under## Option 2: Automated Deployment, skippingh3.evaluate/criteria.md- two criteria use####for their foursub-sections while every other criterion on the page (and every other
criterion added later in the same file) uses
###. Both blocks are fixed,not just the first heading of each.
Skipped levels break the document outline: screen readers and the in-page
"On this page" table of contents are supposed to nest one level at a time,
and the
tocextension'smaxdepthhandling assumes they do.Verification
reports zero
h(n) -> h(n+2)jumps after the change; before it, itreported the eight first-jump sites above plus their continuation headings.
changes. The two explicit
{#...}anchors onagents-cli.md(
{#prerequisites-ad},{#prepare-ad},{#connect-ad},{#deploy-ad},{#adk-agents-cli-changes}) are preserved verbatim, and no page has twoheadings with the same text, so no slug collisions are introduced.
mkdocs build --strictpasses.