You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
fix(docs): give each page its own description and canonical URL, and stop layout shifts - #443
An SEO audit of the docs site (57 prerendered pages) found four problems:
Problem
Before
After
Meta description
All 57 pages had the homepage description (also in og:description and twitter:description); Analog's markdown routes drop the frontmatter description
Each docs page has its own; only the homepage, sponsors and 404 use the site's
Canonical URL
No page had one, and og:url was the homepage on every page
Every page has <link rel="canonical"> and a matching og:url, without a trailing slash, as the sitemap lists them
Redirects
The live site answers every link and sitemap URL with a 307 to the trailing-slash form, where the client briefly renders the homepage before the page
Workers serve /guide from guide/index.html (html_handling: "drop-trailing-slash"); /guide/ redirects to it
Layout shift
Screenshots were an empty placeholder filled in by the browser, so they pushed the page down: desktop CLS about 0.2
<ngmd-image> renders its <figure><img> at build time with the image's width and height; CLS 0.04 to 0.08
Also: kitchen-sink (frontmatter noIndex) was already out of the sitemap but had no noindex tag, so it now gets robots: noindex.
How:
page-meta.plugin.ts adds each markdown page's frontmatter description and noIndex to the virtual:ngmd/page-meta map.
A new PageMetaService, called from the title strategy on every navigation, sets the description, canonical link, og:url, og:title, twitter:title and robots.
image-sizes.ts reads PNG and JPEG sizes from public/ during the build. The image extension writes them on the <img>. MediaEnhancer no longer builds images, only video iframes.
Already fine, no change: unique titles, one <h1> per page, robots.txt with the sitemap, alt text on every content image (the logos are alt="" and aria-hidden), no broken links (the build's link guards), no orphan pages.
How it was verified
pnpm commit:check
pnpm format:check
pnpm typecheck
pnpm docs:test: 110 passed, with new specs for PageMetaService, the image size reader and the image extension
pnpm docs:build, then an audit script over the 57 built pages: unique titles and descriptions (except the three pages above), a canonical link on every page, one <h1> each, noindex only on kitchen-sink
Core Web Vitals in Chromium on the built site, served like Workers will serve it (no trailing slash):
Page
Mobile CLS
Desktop CLS
LCP
/
0
0
< 0.5 s
/inspectors/router
0.069
0.044 to 0.053
< 0.9 s
/inspectors/components
0.083
0.051
< 0.6 s
/getting-started/quick-start
0.073
0.056
< 0.7 s
Before, the desktop CLS on pages with a screenshot was 0.17 to 0.22.
Notes for reviewers
html_handling only takes effect on the next pnpm docs:deploy.
The remaining shift (about 0.05) is <ngmd-hero>, a custom element that renders in the browser and pushes the <h1> down. Prerendering the custom elements would remove it; that's a bigger change and is left out.
After the deploy, resubmitting the sitemap in Search Console would get the canonical, redirect-free URLs recrawled sooner.
Review was skipped as selected files did not have any reviewable changes.
Run configuration
Source mode: Auto
Repository: Unavailable
Branch: Unavailable
File: No configuration file from this repository applied
Commit: Unavailable
Layers: defaults
Review profile: CHILL
Plan: Advanced
Run ID: b6bfeb2d-cf8a-4721-92f6-61797137621e
Commits
Reviewing files that changed from the base of the PR and between e173327 and e37306b.
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
Walkthrough
The docs changes add dimension-aware image rendering and page-specific metadata. Build-time Markdown extensions receive public image dimensions. Page metadata now supports descriptions and no-index directives, and navigation updates social tags and canonical links.
The new utilities read PNG and JPEG dimensions and map them to slash-normalized public URL paths. Tests cover both formats, unsupported SVG input, and directory scanning.
Render images with dimensions apps/docs/src/marked-extensions/ngmd-image.ts, apps/docs/src/marked-extensions/runtime.ts, apps/docs/src/marked-extensions/index.ts, apps/docs/src/app/components/media-enhancer.ts, apps/docs/src/marked-extensions/marked-extensions.spec.ts
The image extension now renders a figure and image, with optional dimensions, lazy loading, decoding, and an escaped caption. Build-time extensions receive sizes read from the public directory. Image hydration was removed; video enhancement remains.
Some builds or image URLs can still produce avoidable layout shifts. These are bounded issues that can be addressed before or shortly after merging.
Pre-merge checks: 5
Check name
Status
Explanation
Description Check
Check skipped - CodeRabbit’s high-level summary is enabled.
Title check
The title names the two main changes, per-page description and canonical URL, plus stopping layout shifts. The changeset covers all three: PageMetaService and page-meta.plugin.ts for description and c…
Docstring Coverage
Docstring coverage is 83.33% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentati…
Linked Issues check
Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check
Check skipped because no linked issues were found for this pull request.
Full details: Title check
Explanation
The title names the two main changes, per-page description and canonical URL, plus stopping layout shifts. The changeset covers all three: PageMetaService and page-meta.plugin.ts for description and canonical URL, and image-sizes/ngmd-image for layout shifts. The title is specific, but it is long at 87 characters and bundles three themes, so it is not a perfect single-focus title. It still clearly reflects the main changes.
Full details: Docstring Coverage
Explanation
Docstring coverage is 83.33% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff with cyclomatic complexity of at least 2. Documentation-only edits and deletions within surviving functions are included; unchanged diff context and fully deleted functions are excluded. Analyzed 6 functions across 12 files. (1 skipped: 1 unsupported.)
Finishing Touches
Generate docstrings
Commit to this branch
Create a new PR
Generate unit tests (beta)
Commit to this branch
Create a new PR
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.
Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.
…stop layout shifts
Every page shipped the homepage description, og:description and og:url,
and none had a canonical link, because Analog's markdown routes drop the
frontmatter description. The page-meta map now carries each page's
description and noIndex, and the title strategy sets the description,
canonical link, og:url and social titles on every navigation. Pages with
`noIndex` get `robots: noindex`, so the kitchen sink stays out of search.
The live site answered every link and sitemap URL with a 307 to its
trailing-slash form, where the client briefly rendered the homepage
before the page. Workers now serve `/guide` from `guide/index.html`
(`html_handling: drop-trailing-slash`).
`<ngmd-image>` rendered an empty placeholder that the browser filled in
later, so screenshots pushed the page down (desktop CLS about 0.2). It
now renders its figure at build time, with the image's width and height
read from public/, so the image is in the prerendered HTML and its space
is reserved.
…d errors (#456)
Three gaps in the image sizes from #443, found in its review:
- A src with a query or fragment (`/a.png?v=2`) missed its size; the
lookup now uses the path.
- The public directory came from `URL.pathname`, which keeps `%20` for a
space, so a checkout path with a space found no images. It now comes
from `import.meta.dirname`.
- Any error while reading the images was swallowed, so the build could
emit images without sizes. Only a missing directory is skipped now.
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
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.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
What and why
An SEO audit of the docs site (57 prerendered pages) found four problems:
og:descriptionandtwitter:description); Analog's markdown routes drop the frontmatterdescriptionog:urlwas the homepage on every page<link rel="canonical">and a matchingog:url, without a trailing slash, as the sitemap lists them/guidefromguide/index.html(html_handling: "drop-trailing-slash");/guide/redirects to it<ngmd-image>renders its<figure><img>at build time with the image'swidthandheight; CLS 0.04 to 0.08Also:
kitchen-sink(frontmatternoIndex) was already out of the sitemap but had nonoindextag, so it now getsrobots: noindex.How:
page-meta.plugin.tsadds each markdown page's frontmatterdescriptionandnoIndexto thevirtual:ngmd/page-metamap.PageMetaService, called from the title strategy on every navigation, sets the description, canonical link,og:url,og:title,twitter:titleandrobots.image-sizes.tsreads PNG and JPEG sizes frompublic/during the build. The image extension writes them on the<img>.MediaEnhancerno longer builds images, only video iframes.Already fine, no change: unique titles, one
<h1>per page,robots.txtwith the sitemap, alt text on every content image (the logos arealt=""andaria-hidden), no broken links (the build's link guards), no orphan pages.How it was verified
pnpm commit:checkpnpm format:checkpnpm typecheckpnpm docs:test: 110 passed, with new specs forPageMetaService, the image size reader and the image extensionpnpm docs:build, then an audit script over the 57 built pages: unique titles and descriptions (except the three pages above), a canonical link on every page, one<h1>each,noindexonly onkitchen-sink//inspectors/router/inspectors/components/getting-started/quick-startBefore, the desktop CLS on pages with a screenshot was 0.17 to 0.22.
Notes for reviewers
html_handlingonly takes effect on the nextpnpm docs:deploy.<ngmd-hero>, a custom element that renders in the browser and pushes the<h1>down. Prerendering the custom elements would remove it; that's a bigger change and is left out.Generated by Claude Code
Summary by CodeRabbit