fix(docs): correct structured-data defects in JSON-LD output - #584
Open
AlexBodner wants to merge 3 commits into
Open
fix(docs): correct structured-data defects in JSON-LD output#584AlexBodner wants to merge 3 commits into
AlexBodner wants to merge 3 commits into
Conversation
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>
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>
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
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.
Five independent defects in the JSON-LD emitted by
docs/hooks/schema_inject.pyanddocs/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:
The visible answer in
docs/index.mdwas 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 aBENCH-XREFnote so the two are updated together perdocs/AGENTS.md.2. BreadcrumbList was never emitted — anywhere
Verified zero
BreadcrumbListblocks on/latest/and/develop/, despite_build_breadcrumbs()being fully implemented.Cause:
_find_in_navonly 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_pathcame back empty for every page and theif not section_path: return Noneguard 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 carrynamebut noitem, 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.logowas relative and inconsistent{{ 'assets/...' | url }}resolves relative to the current page, so the same@id(roboflow.com/#organization) emittedassets/logo-trackers-violet.svgon the homepage and../../assets/logo-trackers-violet.svgtwo levels down — never an absolute URL. Now derived fromsite_url.4.
SoftwareApplicationmissingsoftwareVersionandlicenseBoth are standard properties and both were absent. Version is read from the installed package through a new
on_confighook so it cannot drift frompyproject.toml; license is the Apache-2.0 URL.5.
TechArticle.imagewas the brand SVG on every pageSVG is not an eligible format for Article image rich results, and one generic logo represents no page's content.
publisher.logoalready carries the brand mark, so the field was redundant as well as ineligible. Removed.Verification
mkdocs buildon this branch, inspecting the generated HTML:Home > Trackers > ByteTrack,Home > Usage > Install TrackersOrganization.logoabsolute + identical across pages/latest/assets/logo-trackers-violet.svg→ 200softwareVersion/license2.6.0/ Apache-2.0 URLTechArticle.imageruff checkandruff formatclean. No Python source outsidedocs/hooks/touched.🤖 Generated with Claude Code