Skip to content

fix(docs): working links, better search and AI answers, keyboard and contrast fixes - #243

Merged
alexevladgabriel merged 9 commits into
feat/fumadocs-nextfrom
fix/docs-seo-a11y
Nov 19, 2026
Merged

alexevladgabriel merged 9 commits into
feat/fumadocs-nextfrom
fix/docs-seo-a11y

Conversation

@alexevladgabriel

@alexevladgabriel alexevladgabriel commented Nov 19, 2026 •

Copy link
Copy Markdown
Member

Why

An audit found about 50 docs links that lead to "page not found", the same "Last updated" date on every page, pages that search engines and AI tools can't quote well, and keyboard and screen reader problems. This fixes them, and a new build check stops broken links from coming back.

Search and AI answers

  • Relative links work; check:links fails the build on a broken link, #anchor or redirect.
  • CI fetches the full git history, so each page has its own date.
  • Pages open with a plain sentence; headings start at H2.
  • Clearer titles ("Using Redis with the Panel"); URLs unchanged.
  • llms.txt fixed (Plugins, /sponsor, Hub API); /docs/llms.txt works.
  • Page data names Pelican as author and publisher; pages link their Markdown copy.
  • 301s for old URLs that 404 today (netlify.toml, "Older names"). The Hub picks them up from the docs build (redirects.json).

Accessibility

  • Phone menu: Escape closes it, Tab stays in it, focus returns to the button.
  • Search: focus returns to the button; results count is read out; input has a focus ring.
  • "Skip to content" link; clearer names for the logo link, code blocks and "Open in…".
  • Code comments and dark-mode button edges meet contrast rules (WCAG).
  • Logo: 5 KB WebP instead of 36 KB PNG.

Checked

  • bun test: 161 pass
  • bun run typecheck: ok
  • bun run build: ok; check-links ok on 35 pages (54 broken before)

Not checked

  • No screen reader or browser run of the menu and search changes
  • Cloudflare settings (separate)

…k every link after the build

Pages kept Docusaurus-style relative links (../versioning, ./panel/install). With
trailingSlash the browser resolved them one folder too deep, so about 50 links on 13
pages went to 404s. lib/docs-href.ts resolves them at build time for the HTML pages and
the .md copies alike, and scripts/check-links.mjs (postbuild, check:links) fails the
build on any docs link to a page, file or #anchor that isn't there.
The last-modified plugin reads git. With a depth-1 checkout every page got the date of
the latest commit in the sitemap, article:modified_time, JSON-LD and "Last updated".
…itles

Pages that started with a heading or a warning box now say what they are for in one or two
sentences (facts already in the docs). Headings under the title start at H2 (index,
contributors, standalone install pages, SSL tabs). Vague titles say what and for which
part: "Using Redis with the Panel", "Advanced Wings Configuration", … (URLs unchanged).
Short descriptions for Podman, the webserver config and Cloudflare Tunnel are longer.
…s/llms.txt too

Adds the Plugin Hub, points Support at /sponsor, drops the trailing slash from the Hub's
/eggs and /faq, and links the Hub API docs that exist (hub.pelican.dev/docs/api). The phone
menu's links to the Hub's pages are plain <a>s, so they keep /sponsor instead of /sponsor/.
…atePublished; link the Markdown copy

TechArticle's author and publisher are the Organization the Hub's home page defines
(@id https://pelican.dev/#organization). datePublished is the page's first commit (skipped
on a shallow clone). Each page has <link rel="alternate" type="text/markdown"> to its .md.
…irect target exists

/docs/panel/config, /docs/eggs/creating-a-custom-docker-image, /docs/panel/updating-panel,
/docs/wings/installing-wings, /docs/wings/updating-wings, /docs/team and /updatePanel.sh.
check-links now also fails when a /docs redirect points at a page that isn't built.
…om the keyboard

Phone sidebar: Escape closes it, the page behind it is inert, focus moves in when it opens
and back to the menu button when it closes. Search: focus returns to the button that opened
it, and a live region says how many results there are.
…edges and focus

- "Skip to content" is the first thing Tab reaches.
- The brand link's name includes its visible text; code scroll areas are named; "Open" reads "Open in…".
- Code comments use #8b949e (4.6:1 or more, also on highlighted lines).
- Dark-theme control edges are 3:1 or more; the search input shows a focus ring.
- The logo icon is a 5 KB WebP instead of the 36 KB PNG.
@coderabbitai

coderabbitai Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: c6c355f7-2da5-4c03-9a0a-59f6bc17bef2

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • Trigger review
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

Four descriptions ran to 166-180 characters and the Comparison title to 66
with ' | Pelican Docs'; Google cuts them at about 160 and 60.
@alexevladgabriel
alexevladgabriel merged commit 4fb10ce into feat/fumadocs-next Nov 19, 2026
4 checks passed
@alexevladgabriel
alexevladgabriel deleted the fix/docs-seo-a11y branch November 19, 2026 23:46
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