Agent readability (a14y) fixes: sitemap lastmod, JSON-LD dateModified, category/doc descriptions#546
Merged
Merged
Conversation
Docusaurus already computes real, git-based lastUpdatedAt per page (showLastUpdateTime was already on) but the sitemap plugin's lastmod option defaults to null/disabled, so sitemap.xml had zero <lastmod> tags across all 443 entries. Resolves the a14y sitemap-xml.has-lastmod check -- verified locally: 422/443 URLs now carry a real <lastmod> (the remainder are generated routes like /docs/search with no underlying markdown file to source a date from). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Wraps DocItem/Layout and DocCategoryGeneratedIndexPage to emit a WebPage JSON-LD node with dateModified, sourced from Docusaurus's own git-based lastUpdatedAt metadata for real doc pages (already computed since showLastUpdateTime was on), falling back to build time for auto-generated category index pages. Resolves the a14y html.json-ld.date-modified check. Note: this does NOT add a BreadcrumbList -- Docusaurus 3.x's DocBreadcrumbs component already emits an accurate one (real sidebar titles) on every doc/category page via its built-in useBreadcrumbsStructuredData hook. An earlier manual check of a production page appeared to show this missing, but that was a bug in my own regex (didn't account for react-helmet's data-rh attribute) -- verified with a corrected check that it's already there. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Adds a link.description to every docs/**/_category_.yml that was missing one (only 1 of 36 categories already had it). Docusaurus surfaces this as both the meta description and og:description on the auto-generated category index page. Resolves the a14y html.meta-description and html.og-description checks for category pages -- verified in the build output that both tags render with the correct content on multiple category pages. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Adds a description: frontmatter field to every markdown doc that was missing one (62 total found; docs/cloud/migrate/_migration_options.mdx excluded since its leading underscore means Docusaurus treats it as a partial, not a routed page). Docusaurus surfaces this as both the meta description and og:description tags. Resolves the remaining a14y html.meta-description and html.og-description failures -- verified in the build output on several pages (about/faq, managing-dragonfly/acl, cloud/sso/okta). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
PR Summary by QodoImprove docs structured data and metadata (sitemap lastmod, JSON-LD dateModified, descriptions)
AI Description
Diagram
High-Level Assessment
Files changed (100)
|
Code Review by Qodo
1.
|
![qodo-free-for-open-source-projects[bot]](https://avatars.githubusercontent.com/in/1068000?s=60&v=4){kind=small}
Two issues from Qodo's review of #546: 1. buildPageJsonLd() fell back to Date.now() for category pages (which have no per-file date), so dateModified drifted on every rebuild even with zero content changes. Now sourced from a single siteConfig.customFields.buildTimeIso value captured once at config load, so every page in the same build shares one stable timestamp. dateModifiedMs is now a required param -- no more silent fallback. 2. buildPageJsonLd() hardcoded the site origin instead of reading it from docusaurus.config.mjs. Both wrappers now pass useDocusaurusContext().siteConfig.url in instead. Verified in the build output: two different category pages now emit the exact same dateModified (proving it's one stable per-build value, not per-page Date.now()), while a real doc page keeps its accurate git-based date. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2 tasks
worldsoup
added a commit
that referenced
this pull request
Jul 10, 2026
…imum (#547) Lengthen and fix 12 command reference descriptions Re-running the a14y audit after #546 landed found 12 pages still failing html.meta-description -- these already had a description (so they weren't caught by the "missing entirely" pass in #546), just under the 50-char minimum. Also fixes ACL GENPASS's description, which was a copy-paste of ACL DRYRUN's ("Simulate execution of a command from a user") and didn't describe what the command actually does. Co-authored-by: Nicholas Gottlieb <nicholasgottlieb@Nicholass-MacBook-Pro-2.local> Co-authored-by: Claude Sonnet 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
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.
Summary
Fixes from an a14y (agent-readability) audit run against
https://www.dragonflydb.io/docs(score 68/100, 200 pages sampled). Companion to dragonflydb/website-cms#242 / #243, which covered the marketing site.lastmod(docusaurus.config.mjs): the sitemap plugin'slastmodoption defaulted to disabled, sositemap.xmlhad zero<lastmod>tags across all 443 entries even though Docusaurus already computes real git-basedlastUpdatedAtper page (showLastUpdateTimewas already on). One-line config fix — verified locally: 422/443 URLs now carry a real<lastmod>.dateModified: newsrc/theme/DocItem/Layoutandsrc/theme/DocCategoryGeneratedIndexPagewrappers emit aWebPageJSON-LD node withdateModified, sourced from Docusaurus's real git-based metadata for doc pages, falling back to build time for auto-generated category pages.link.descriptionto all 35docs/**/_category_.ymlfiles that were missing one (34 had none at all).description:frontmatter to 61 of 62 markdown files missing one (the 62nd,_migration_options.mdx, is a Docusaurus partial excluded from routing by its leading underscore, so it was skipped as not applicable).Correction made along the way
I initially thought
BreadcrumbListJSON-LD was missing site-wide and started adding one — turned out Docusaurus 3.x'sDocBreadcrumbscomponent already emits an accurate one out of the box (useBreadcrumbsStructuredData). My first "it's missing" finding was a bug in my own verification regex (didn't account for react-helmet'sdata-rhattribute), not an actual gap. Removed the redundant breadcrumb code before committing — only thedateModifiedaddition, which is genuinely new, made it into the commit.Explicitly out of scope (per the audit plan)
.mdmirrors, content negotiation, alternate<link>) — large separate project, default-skip.llms-txt.md-extensions—llms.txtis served bywebsite-cms, not this repo.html.text-ratio— would mean stripping legitimate sidebar/nav/TOC chrome; not proposing a fix./docs/search's compounding failures — Docusaurus's built-in search page, would need swizzling the search plugin; low value.Test plan
yarn buildsucceeds with no errors after every changesitemap.xmllastmod coverage (422/443), JSON-LDWebPage/dateModifiedon both a doc page and a category page with no duplicate/conflicting structured data, category page meta/og descriptions, and doc page meta/og descriptions across multiple sampled pages🤖 Generated with Claude Code