Skip to content

dev/TODO: Record the docs site audit findings that have no PR yet #2005

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
marcleblanc2 wants to merge 2 commits into
base: main
Choose a base branch
from
Draft

dev/TODO: Record the docs site audit findings that have no PR yet #2005

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b7dd235
dev/TODO: Record the docs site audit findings that have no PR yet
marcleblanc2 Sep 17, 2026
70aba05
dev/TODO: Fix spelling flagged by CSpell
marcleblanc2 Sep 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
29 changes: 29 additions & 0 deletions dev/TODO.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,3 +4,32 @@
React Compiler ESLint rules `react-hooks/refs`, `react-hooks/set-state-in-effect`
and `react-hooks/static-components` can go back to `error` in `eslint.config.mjs`
(31 of the 39 warnings from `pnpm run lint` are in that directory)

## Docs site audit leftovers

Findings from the crawl of all 502 pages
(<https://ampcode.com/threads/T-01a0ae50-f7f0-779c-aa66-3887c9953e33>)
with no PR yet. Fixes with PRs: #1998–#2004.

- Cloudflare AI Labyrinth injects a hidden `<a href="/cdn-cgi/content?id=…">`
as the first child of `<body>` for suspected bots, so React hydration fails
(#418) on 102 of 502 pages. Cloudflare setting: exclude
`sourcegraph.com/docs/*` from AI Labyrinth.
- Every page has the same `<meta name="description">`
(`src/app/layout.tsx`); `generateMetadata` in `src/app/[...slug]/page.tsx`
never sets one. Derive it from the first paragraph.
- Duplicate `<title>`s: the title is the first heading only, so 4 pages are
"How-to guides", 3 "FAQs", 3 "How-tos", … Suffix with the parent section.
- `src/app/sitemap.ts`: the last-modified time is the build time for every
page, and both `/docs` and `/docs/` are listed.
- `docs/self-hosted/postgresql-collation-version-mismatch-resolution.mdx`
renders 10 `<h1>`s; demote all but the first.
- `docs/integration/gitlab.mdx:29` embeds `img/gitlab-code-intel.gif`, but
nothing serves `docs/**/img` (404); move it to `public/` after #1977 lands.
The other ~50 files in `docs/integration/img/` are orphaned.
- Code-comment color in the syntax theme is `#B362FF` on `#2d2b55` (3.84:1,
below WCAG AA); the rest of the contrast findings landed in #1995.
- `/admin/config/site-config#<key>` anchors (19 inbound links) do not exist:
the schema renderer emits no per-key ids. Deferred by #1925.
- `/self-hosted/observability/dashboards` is generated from the
sourcegraph/sourcegraph sync (#1971) and is a giant page; fix upstream.
Loading