chore: upgrade just-the-docs v0.5→v0.10.1, fix SEO, widen content

[ankurs]

Summary

• Theme upgrade: just-the-docs v0.5.0 → v0.10.1 (Jekyll 4.3 → 4.4.1), migrated GA tracking from deprecated ga_tracking to custom _includes/head_custom.html, fixed repository and baseurl config
• SEO fixes: expanded 3 short meta descriptions to 120+ chars, eliminated duplicate nav_order, renumbered all top-level pages, added nav_order to all 16 howto child pages, created explicit robots.txt with production sitemap URL
• Layout: widened main content area from 50rem (800px) to 66rem (1056px) via _sass/custom/setup.scss
• Tests: fixed Playwright strict mode violations for v0.10.1 DOM changes; all 57 tests pass

Test plan

• bundle exec jekyll build succeeds without errors
• All 57 Playwright tests pass (npx playwright test)
• robots.txt contains https://docs.coldbrew.cloud/sitemap.xml
• GA tag present in rendered HTML
• Visual check after deploy: sidebar ordering, content width, search

Summary by CodeRabbit

• New Features

  • Added analytics tracking to the docs site
  • Added robots/sitemap configuration for improved search engine visibility
  • Documented built-in Proto validation and broader protobuf content-type support

• Chores

  • Updated documentation theme dependency to a newer release
  • Reorganized navigation ordering across documentation for improved discoverability
  • Adjusted site configuration and content width styling

[coderabbitai]

Warning

Rate limit exceeded

@ankurs has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 14 minutes and 51 seconds before requesting another review.

Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 14 minutes and 51 seconds.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 6145dfa5-e0b8-4238-9dbc-8e8dc4439646

📥 Commits

Reviewing files that changed from the base of the PR and between a8de6a2 and d547397.

📒 Files selected for processing (4)

• .github/workflows/jekyll.yml
• .github/workflows/playwright.yml
• _includes/head_custom.html
• robots.txt

📝 Walkthrough

Walkthrough

This PR reorders many docs via Jekyll front-matter nav_order, bumps the just-the-docs theme version, adds Google Analytics gtag, adjusts site config (baseurl, repository, removed ga_tracking), adds robots.txt, sets a SCSS $content-width, and scopes Playwright selectors to .first().

Changes

Cohort / File(s)	Summary
Documentation Navigation & Metadata FAQ.md, Packages.md, architecture.md, config-reference.md, integrations.md, Index.md, howto/APIs.md, howto/Debugging.md, howto/Log.md, howto/Metrics.md, howto/Tracing.md, howto/data-builder.md, howto/errors.md, howto/gRPC.md, howto/index.md, howto/interceptors.md, howto/private-modules.md, howto/production.md, howto/signals.md, howto/swagger.md, howto/testing.md, howto/vtproto.md, howto/workers.md	Updated nav_order across many pages to change navigation ordering; a few front-matter description updates (e.g., integrations.md, howto/gRPC.md, howto/Metrics.md, Index.md).
Site Configuration _config.yml	Changed baseurl "/" → "", updated repository value, removed ga_tracking field and a commented color_scheme line.
Analytics Implementation _includes/head_custom.html	Added gtag.js snippet: dataLayer init, gtag function, gtag('js', new Date()) and gtag('config', 'G-ZRR08Y74FZ').
Theme Dependency Gemfile	Bumped just-the-docs gem from 0.5.0 → 0.10.1.
Styling _sass/custom/setup.scss	Added $content-width: 66rem variable.
SEO / Crawling robots.txt	Added robots.txt allowing all crawlers and pointing to {{ site.url }}/sitemap.xml.
Test Adjustments tests/content.spec.ts	Scoped Playwright page.locator("main, .main-content") calls to .first().textContent() to target the first matched element.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• Docs overhaul: cleanup, fixes, and improvements #38: Updates the same Playwright test file (tests/content.spec.ts) by scoping .textContent() calls to .first().
• Docs: improve approachability, discoverability, and content depth #39: Overlaps on broad documentation front-matter edits and navigation ordering across many howto and doc pages.
• docs: add protovalidate to homepage, architecture, config, and interceptors howto #59: Related documentation change to Index.md adding/proclaiming Protovalidate-based request validation.

Poem

🐰 I hopped through front-matter and made a small tweak,
I set widths and tracking for each doc I seek,
I nudged nav order so pages align,
I left a robots.txt sign,
Happy hops — the docs now peek! 🥕✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the three main themes of the changeset: theme upgrade (just-the-docs v0.5→v0.10.1), SEO improvements (Google Analytics migration, robots.txt, nav ordering, expanded descriptions), and layout widening (content width increase).
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch chore/upgrade-theme-seo-fixes

---

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

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

Upgrades the docs site theme (just-the-docs) and adjusts site configuration/content to restore SEO correctness, improve navigation ordering, and update tests/layout for the new theme version.

Changes:

• Upgraded just-the-docs to v0.10.1 (and Jekyll dependency set via lockfile), plus config updates (repository/baseurl) and GA moved to a custom head include.
• SEO/navigation improvements: longer meta descriptions, consistent/complete nav_order across top-level + How To children, and a generated robots.txt with sitemap link.
• Layout/test updates: widen content area via Sass variable and fix Playwright strict-mode selector behavior.

Reviewed changes

Copilot reviewed 28 out of 29 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/content.spec.ts	Makes content lookups strict-mode-safe by selecting the first matching main container.
robots.txt	Adds a Jekyll/Liquid-rendered robots file with a sitemap URL.
Packages.md	Adjusts top-level nav ordering.
integrations.md	Expands meta description and adjusts nav ordering.
howto/index.md	Adjusts How To section ordering.
howto/APIs.md	Adds nav_order for How To child ordering.
howto/gRPC.md	Adds nav_order and expands description.
howto/Log.md	Adds nav_order for How To child ordering.
howto/errors.md	Adds nav_order for How To child ordering.
howto/Tracing.md	Adds nav_order for How To child ordering.
howto/Metrics.md	Adds nav_order and expands description.
howto/interceptors.md	Adds nav_order for How To child ordering.
howto/Debugging.md	Adds nav_order for How To child ordering.
howto/signals.md	Adds nav_order for How To child ordering.
howto/swagger.md	Adds nav_order for How To child ordering.
howto/data-builder.md	Adds nav_order for How To child ordering.
howto/vtproto.md	Adds nav_order for How To child ordering.
howto/production.md	Adds nav_order for How To child ordering.
howto/testing.md	Adds nav_order for How To child ordering.
howto/workers.md	Adds nav_order for How To child ordering.
howto/private-modules.md	Adds nav_order for How To child ordering.
FAQ.md	Adjusts top-level nav ordering.
config-reference.md	Adjusts top-level nav ordering.
architecture.md	Adjusts top-level nav ordering.
Gemfile	Bumps just-the-docs version requirement.
Gemfile.lock	Updates locked Ruby dependencies for Jekyll/just-the-docs upgrade.
_sass/custom/setup.scss	Widens main content area by overriding theme Sass variable.
_includes/head_custom.html	Injects GA tag via just-the-docs head customization hook.
_config.yml	Fixes baseurl/repository and removes deprecated GA config key.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

tests/content.spec.ts (1)

87-88: Consider unifying selector patterns across test files.

The fix is correct. However, navigation.spec.ts uses #main-content, .main-content, main (three selectors, ID-first) while this file uses main, .main-content (two selectors, element-first). Unifying these patterns would improve maintainability if the DOM structure changes again.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@tests/content.spec.ts` around lines 87 - 88, Unify the selector pattern used
in tests by changing the locator call that assigns pageText (page.locator(...))
to use the same selector list as navigation.spec.ts ("#main-content,
.main-content, main") instead of the current "main, .main-content"; update the
page.locator invocation in tests/content.spec.ts (the code that produces
pageText) so it uses the ID-first, class, element order to keep patterns
consistent across test files.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@Gemfile`:
- Line 4: The Gemfile currently uses gem "just-the-docs", "0.10.1" which pulls a
public_suffix requiring Ruby >= 3.2 and breaks CI running Ruby 3.1; fix by
either updating your CI jobs to use Ruby 3.2+ in the GitHub Actions workflow
files (playwright.yml and jekyll.yml) or pinning the older public_suffix in the
Gemfile by adding a line to constrain public_suffix to "< 7.0" so bundle install
succeeds under Ruby 3.1.

---

Nitpick comments:
In `@tests/content.spec.ts`:
- Around line 87-88: Unify the selector pattern used in tests by changing the
locator call that assigns pageText (page.locator(...)) to use the same selector
list as navigation.spec.ts ("#main-content, .main-content, main") instead of the
current "main, .main-content"; update the page.locator invocation in
tests/content.spec.ts (the code that produces pageText) so it uses the ID-first,
class, element order to keep patterns consistent across test files.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: cdf53714-815e-4a71-be60-dd1595caaf7b

📥 Commits

Reviewing files that changed from the base of the PR and between cb32d61 and a220476.

⛔ Files ignored due to path filters (1)

• Gemfile.lock is excluded by !**/*.lock

📒 Files selected for processing (28)

• FAQ.md
• Gemfile
• Packages.md
• _config.yml
• _includes/head_custom.html
• _sass/custom/setup.scss
• architecture.md
• config-reference.md
• howto/APIs.md
• howto/Debugging.md
• howto/Log.md
• howto/Metrics.md
• howto/Tracing.md
• howto/data-builder.md
• howto/errors.md
• howto/gRPC.md
• howto/index.md
• howto/interceptors.md
• howto/private-modules.md
• howto/production.md
• howto/signals.md
• howto/swagger.md
• howto/testing.md
• howto/vtproto.md
• howto/workers.md
• integrations.md
• robots.txt
• tests/content.spec.ts