Skip to content

fix(docs): correct structured-data defects in JSON-LD output - #584

Open
AlexBodner wants to merge 3 commits into
developfrom
fix/docs-schema-correctness
Open

fix(docs): correct structured-data defects in JSON-LD output#584
AlexBodner wants to merge 3 commits into
developfrom
fix/docs-schema-correctness

Conversation

@AlexBodner

@AlexBodner AlexBodner commented Aug 25, 2026

Copy link
Copy Markdown
Collaborator

Five independent defects in the JSON-LD emitted by docs/hooks/schema_inject.py and docs/overrides/main.html. Grouped because they share the same two files and the same reviewer context; none is coupled to the others.

Found while auditing the docs for search/AI-answer visibility. Unlike #582 and #583, none of these is fixed by cutting a release — they are live on /develop/ today.

1. FAQPage markup contradicts the visible answer (and the benchmark tables)

The schema still claimed:

Start with ByteTrack — it performs best across two out of four benchmarks

The visible answer in docs/index.md was already corrected to credit McByte for accuracy and BoT-SORT for camera motion, and the Default HOTA tables agree with the visible text, not the markup. Google requires FAQPage markup to match visible content, so this was both a factual and a policy problem. Synced, with a BENCH-XREF note so the two are updated together per docs/AGENTS.md.

2. BreadcrumbList was never emitted — anywhere

Verified zero BreadcrumbList blocks on /latest/ and /develop/, despite _build_breadcrumbs() being fully implemented.

Cause: _find_in_nav only appended a section when it resolved to a URL. But nav sections (Home, Usage, Tuning, Trackers) are pure groupings with no page behind them, so mkdocs gives them no URL and no file — section_path came back empty for every page and the if not section_path: return None guard bailed out every time.

Now records sections by name (position + name are sufficient per schema.org) and drops the guard.

Note that intermediate ListItems for URL-less sections carry name but no item, because there is no page to link to. That is valid schema.org, but Google's rich-result guidance is stricter about intermediate items, so display is not guaranteed. The fallback is the status quo, no breadcrumb shown, so this cannot regress anything.

3. Organization.logo was relative and inconsistent

{{ 'assets/...' | url }} resolves relative to the current page, so the same @id (roboflow.com/#organization) emitted assets/logo-trackers-violet.svg on the homepage and ../../assets/logo-trackers-violet.svg two levels down — never an absolute URL. Now derived from site_url.

4. SoftwareApplication missing softwareVersion and license

Both are standard properties and both were absent. Version is read from the installed package through a new on_config hook so it cannot drift from pyproject.toml; license is the Apache-2.0 URL.

5. TechArticle.image was the brand SVG on every page

SVG is not an eligible format for Article image rich results, and one generic logo represents no page's content. publisher.logo already carries the brand mark, so the field was redundant as well as ineligible. Removed.

Verification

mkdocs build on this branch, inspecting the generated HTML:

Check Result
All JSON-LD blocks parse as valid JSON ✅ 4 / 3 / 3 blocks on homepage / ByteTrack / Install
Breadcrumbs emitted Home > Trackers > ByteTrack, Home > Usage > Install Trackers
Organization.logo absolute + identical across pages
Logo path resolves under the versioned prefix /latest/assets/logo-trackers-violet.svg → 200
softwareVersion / license 2.6.0 / Apache-2.0 URL
TechArticle.image ✅ absent
FAQ markup matches the rendered answer

ruff check and ruff format clean. No Python source outside docs/hooks/ touched.

🤖 Generated with Claude Code

Five independent defects in the schema emitted by docs/hooks/schema_inject.py
and docs/overrides/main.html:

1. FAQPage answer for "Which tracker should I use?" still claimed ByteTrack
   "performs best across two out of four benchmarks". The visible answer in
   docs/index.md was already updated to credit McByte for accuracy and BoT-SORT
   for camera motion, so the markup contradicted both the rendered page and the
   Default HOTA tables. Google requires FAQPage markup to match visible content;
   sync it and add a BENCH-XREF note so the two stay together.

2. BreadcrumbList was never emitted on any page. _find_in_nav only recorded a
   section when it resolved to a URL, but nav sections (Home, Usage, Tuning,
   Trackers) are pure groupings with no page behind them, so section_path was
   always empty and the `if not section_path` guard returned None every time.
   Record sections by name and drop the guard.

3. Organization.logo used the `| url` filter, which is relative to the current
   page — "assets/..." at the root, "../../assets/..." deeper. One @id therefore
   carried a different logo value per page and never an absolute URL. Derive it
   from site_url instead.

4. SoftwareApplication was missing softwareVersion and license. Version comes
   from the installed package via a new on_config hook so it cannot drift from
   pyproject.toml; license is the Apache-2.0 URL.

5. TechArticle.image pointed at the brand SVG on every page. SVG is not an
   eligible Article image format and the logo represents no page's content;
   publisher.logo already carries the mark. Drop it.

Verified with mkdocs build: all JSON-LD blocks parse, breadcrumbs render as
"Home > Trackers > ByteTrack" and "Home > Usage > Install Trackers", logo is
absolute and identical across pages, softwareVersion resolves to 2.6.0, and the
FAQ markup matches the rendered answer.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@AlexBodner
AlexBodner requested a review from SkalskiP as a code owner August 25, 2026 12:29
AlexBodner and others added 2 commits August 25, 2026 09:42
Running ruff format while fixing the schema defects also reformatted four
pre-existing hunks unrelated to this PR (the file was already not
format-clean on develop, and CI does not enforce ruff-format). Restore them
so the diff only contains the structured-data changes.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The FAQPage answer for "What MOT datasets does the library support?" was a
stale copy of the visible answer in docs/index.md, and it published an
invalid command: `trackers download <dataset>`. The CLI requires the --name
flag (`trackers download --name <dataset>`, verified against
`trackers download --help`), which the visible docs already use.

Same defect class as the "Which tracker should I use?" answer in the previous
commit: markup hand-copied from index.md and not updated with it. All five
FAQ answers now match the rendered page verbatim.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant