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

ankurs · web-flow · commit ce2d12232aa6 · 2026-04-06T23:07:28.000+08:00
* chore: upgrade just-the-docs v0.5.0 to v0.10.1, fix SEO, widen content area

- Upgrade just-the-docs theme from v0.5.0 to v0.10.1 (Jekyll 4.3→4.4.1)
- Migrate GA tracking from deprecated ga_tracking config to custom head include
- Fix repository config and baseurl for correct local/production builds
- Fix 3 short meta descriptions (integrations, gRPC, Metrics) to 120+ chars
- Eliminate duplicate nav_order (architecture + config-reference both had 5)
- Renumber all top-level page nav_order values for contiguous sidebar ordering
- Add nav_order to all 16 howto child pages for deterministic sidebar order
- Create explicit robots.txt with production sitemap URL
- Widen main content area from 50rem (800px) to 66rem (1056px)
- Fix Playwright strict mode violations in content tests

* docs: add protovalidate and content-type to homepage DRY table

* fix: address PR review — robots.txt layout, GA guard, Ruby 3.2 in CI

- robots.txt: add layout: null and sitemap: false to prevent HTML wrapping
- head_custom.html: guard GA snippet with jekyll.environment == production
- CI workflows: upgrade Ruby 3.1 → 3.2 (public_suffix 7.x requires &gt;= 3.2)
diff --git a/.github/workflows/jekyll.yml b/.github/workflows/jekyll.yml
@@ -36,7 +36,7 @@ jobs:
       - name: Setup Ruby
         uses: ruby/setup-ruby@c515ec17f69368147deb311832da000dd229d338 # v1.297.0
         with:
-          ruby-version: '3.1' # Not needed with a .ruby-version file
+          ruby-version: '3.2' # public_suffix 7.x requires Ruby >= 3.2
           bundler-cache: true # runs 'bundle install' and caches installed gems automatically
           cache-version: 0 # Increment this number if you need to re-download cached gems
       - name: Setup Pages
diff --git a/.github/workflows/playwright.yml b/.github/workflows/playwright.yml
@@ -20,7 +20,7 @@ jobs:
       - name: Setup Ruby
         uses: ruby/setup-ruby@c515ec17f69368147deb311832da000dd229d338 # v1.297.0
         with:
-          ruby-version: "3.1"
+          ruby-version: "3.2"
           bundler-cache: true
 
       - name: Build Jekyll site
diff --git a/FAQ.md b/FAQ.md
@@ -1,7 +1,7 @@
 ---
 layout: default
 title: "FAQ"
-nav_order: 8
+nav_order: 7
 description: "Frequently asked questions about ColdBrew: gRPC framework configuration, interceptors, tracing, and troubleshooting"
 permalink: /faq
 ---
diff --git a/Gemfile b/Gemfile
@@ -1,7 +1,7 @@
 source 'https://rubygems.org'
 
 gem "jekyll", "~> 4.3"
-gem "just-the-docs", "0.5.0"
+gem "just-the-docs", "0.10.1"
 gem "jekyll-default-layout"
 gem "jekyll-github-metadata", ">= 2.15"
 gem "webrick", "~> 1.7"
diff --git a/Gemfile.lock b/Gemfile.lock
@@ -1,12 +1,12 @@
 GEM
   remote: https://rubygems.org/
   specs:
-    addressable (2.8.4)
-      public_suffix (>= 2.0.2, < 6.0)
+    addressable (2.9.0)
+      public_suffix (>= 2.0.2, < 8.0)
     base64 (0.3.0)
     bigdecimal (4.0.1)
     colorator (1.1.0)
-    concurrent-ruby (1.2.2)
+    concurrent-ruby (1.3.6)
     csv (3.3.5)
     em-websocket (0.5.3)
       eventmachine (>= 0.12.9)
@@ -16,23 +16,36 @@ GEM
       faraday-net_http (>= 2.0, < 3.1)
       ruby2_keywords (>= 0.0.4)
     faraday-net_http (3.0.2)
-    ffi (1.15.5)
+    ffi (1.17.4-arm64-darwin)
+    ffi (1.17.4-x86_64-darwin)
+    ffi (1.17.4-x86_64-linux-gnu)
     forwardable-extended (2.6.0)
-    google-protobuf (3.22.3)
-    http_parser.rb (0.8.0)
-    i18n (1.12.0)
+    google-protobuf (4.34.1-arm64-darwin)
+      bigdecimal
+      rake (~> 13.3)
+    google-protobuf (4.34.1-x86_64-darwin)
+      bigdecimal
+      rake (~> 13.3)
+    google-protobuf (4.34.1-x86_64-linux-gnu)
+      bigdecimal
+      rake (~> 13.3)
+    http_parser.rb (0.8.1)
+    i18n (1.14.8)
       concurrent-ruby (~> 1.0)
-    jekyll (4.3.2)
+    jekyll (4.4.1)
       addressable (~> 2.4)
+      base64 (~> 0.2)
       colorator (~> 1.0)
+      csv (~> 3.0)
       em-websocket (~> 0.5)
       i18n (~> 1.0)
       jekyll-sass-converter (>= 2.0, < 4.0)
       jekyll-watch (~> 2.0)
+      json (~> 2.6)
       kramdown (~> 2.3, >= 2.3.1)
       kramdown-parser-gfm (~> 1.0)
       liquid (~> 4.0)
-      mercenary (>= 0.3.6, < 0.5)
+      mercenary (~> 0.3, >= 0.3.6)
       pathutil (~> 0.9)
       rouge (>= 3.0, < 5.0)
       safe_yaml (~> 1.0)
@@ -43,8 +56,10 @@ GEM
     jekyll-github-metadata (2.16.0)
       jekyll (>= 3.4, < 5.0)
       octokit (>= 4, < 7, != 4.4.0)
-    jekyll-sass-converter (3.0.0)
-      sass-embedded (~> 1.54)
+    jekyll-include-cache (0.2.1)
+      jekyll (>= 3.7, < 5.0)
+    jekyll-sass-converter (3.1.0)
+      sass-embedded (~> 1.75)
     jekyll-seo-tag (2.8.0)
       jekyll (>= 3.8, < 5.0)
     jekyll-sitemap (1.4.0)
@@ -54,16 +69,19 @@ GEM
       nokogiri (~> 1.10)
     jekyll-watch (2.2.1)
       listen (~> 3.0)
-    just-the-docs (0.5.0)
+    json (2.19.3)
+    just-the-docs (0.10.1)
       jekyll (>= 3.8.5)
+      jekyll-include-cache
       jekyll-seo-tag (>= 2.0)
       rake (>= 12.3.1)
-    kramdown (2.4.0)
-      rexml
+    kramdown (2.5.2)
+      rexml (>= 3.4.4)
     kramdown-parser-gfm (1.1.0)
       kramdown (~> 2.0)
     liquid (4.0.4)
-    listen (3.8.0)
+    listen (3.10.0)
+      logger
       rb-fsevent (~> 0.10, >= 0.10.3)
       rb-inotify (~> 0.9, >= 0.9.10)
     logger (1.7.0)
@@ -78,29 +96,29 @@ GEM
     ostruct (0.6.3)
     pathutil (0.16.2)
       forwardable-extended (~> 2.6)
-    public_suffix (5.0.1)
+    public_suffix (7.0.5)
     racc (1.6.2)
-    rake (13.0.6)
+    rake (13.3.1)
     rb-fsevent (0.11.2)
-    rb-inotify (0.10.1)
+    rb-inotify (0.11.1)
       ffi (~> 1.0)
-    rexml (3.2.5)
-    rouge (3.30.0)
+    rexml (3.4.4)
+    rouge (4.7.0)
     ruby2_keywords (0.0.5)
     safe_yaml (1.0.5)
-    sass-embedded (1.58.3-arm64-darwin)
-      google-protobuf (~> 3.21)
-    sass-embedded (1.58.3-x86_64-darwin)
-      google-protobuf (~> 3.21)
-    sass-embedded (1.58.3-x86_64-linux-gnu)
-      google-protobuf (~> 3.21)
+    sass-embedded (1.99.0-arm64-darwin)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.99.0-x86_64-darwin)
+      google-protobuf (~> 4.31)
+    sass-embedded (1.99.0-x86_64-linux-gnu)
+      google-protobuf (~> 4.31)
     sawyer (0.9.2)
       addressable (>= 2.3.5)
       faraday (>= 0.17.3, < 3)
     terminal-table (3.0.2)
       unicode-display_width (>= 1.1.1, < 3)
-    unicode-display_width (2.4.2)
-    webrick (1.8.1)
+    unicode-display_width (2.6.0)
+    webrick (1.9.2)
 
 PLATFORMS
   arm64-darwin-22
@@ -117,7 +135,7 @@ DEPENDENCIES
   jekyll-github-metadata (>= 2.15)
   jekyll-sitemap
   jekyll-target-blank
-  just-the-docs (= 0.5.0)
+  just-the-docs (= 0.10.1)
   logger
   ostruct
   webrick (~> 1.7)
diff --git a/Index.md b/Index.md
@@ -146,7 +146,9 @@ ColdBrew handles all of it. You write business logic, ColdBrew handles everythin
 | Nothing | Prometheus metrics at `/metrics` — per-method latency, error rate, QPS |
 | Nothing | Health/ready probes, graceful shutdown, [pprof] profiling |
 | Nothing | Interceptor chain: logging, tracing, metrics, panic recovery |
+| Proto validation annotations | Request validation via [Protovalidate] — `InvalidArgument` on failure, covers gRPC and HTTP |
 | Nothing | [vtprotobuf] codec — up to ~4x faster proto marshal |
+| Nothing | HTTP content negotiation — JSON, `application/proto`, `application/protobuf` out of the box |
 | Nothing | HTTP [gzip/zstd][zstd] compression, container-aware [GOMAXPROCS][automaxprocs] |
 
 New services inherit all of this automatically via the [cookiecutter template](/getting-started) — zero boilerplate to write, zero infrastructure to maintain.
@@ -157,7 +159,7 @@ ColdBrew composes proven Go libraries — not replacements:
 
 | Category | Libraries |
 |----------|----------|
-| **API** | [grpc] + [grpc-gateway] — gRPC server with automatic REST gateway and Swagger UI |
+| **API** | [grpc] + [grpc-gateway] — gRPC server with automatic REST gateway and Swagger UI; [Protovalidate] — request validation |
 | **Observability** | [OpenTelemetry] + [Jaeger] — distributed tracing; [Prometheus] + [go-grpc-middleware] — metrics |
 | **Monitoring** | [New Relic] — APM; [Sentry] — error tracking and alerting |
 | **Performance** | [vtprotobuf] — fast serialization; [klauspost/compress][zstd] — gzip/zstd HTTP compression |
diff --git a/Packages.md b/Packages.md
@@ -3,7 +3,7 @@ layout: default
 title: Packages
 description: "ColdBrew Go packages: core, interceptors, errors, log, tracing, options, grpcpool, and data-builder API reference"
 permalink: /packages
-nav_order: 9
+nav_order: 8
 ---
 # Packages
 {: .no_toc }
diff --git a/_config.yml b/_config.yml
@@ -1,8 +1,8 @@
 title: ColdBrew
 description: "ColdBrew is a Go microservice framework for building production-grade gRPC services with built-in observability, resilience, and HTTP gateway support."
-baseurl: "/" # the subpath of your site, e.g. /blog
+baseurl: "" # the subpath of your site, e.g. /blog
 url: "https://docs.coldbrew.cloud"
-repository: go-coldbrew/
+repository: go-coldbrew/docs.coldbrew.cloud
 logo: "/assets/images/coldbrew.png"
 favicon_ico: "/assets/images/coldbrew.ico"
 
@@ -50,9 +50,6 @@ gh_edit_branch: "main" # the branch that your docs is served from
 # gh_edit_source: docs # the source that your files originate from
 gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into the editor immediately
 
-ga_tracking: "G-ZRR08Y74FZ"
-
-#color_scheme: dark
 plugins:
   - jekyll-default-layout
   - jekyll-seo-tag
diff --git a/_includes/head_custom.html b/_includes/head_custom.html
@@ -0,0 +1,10 @@
+{% if jekyll.environment == 'production' %}
+<!-- Google tag (gtag.js) -->
+<script async src="https://www.googletagmanager.com/gtag/js?id=G-ZRR08Y74FZ"></script>
+<script>
+  window.dataLayer = window.dataLayer || [];
+  function gtag(){dataLayer.push(arguments);}
+  gtag('js', new Date());
+  gtag('config', 'G-ZRR08Y74FZ');
+</script>
+{% endif %}
diff --git a/_sass/custom/setup.scss b/_sass/custom/setup.scss
@@ -0,0 +1 @@
+$content-width: 66rem;
diff --git a/architecture.md b/architecture.md
@@ -1,7 +1,7 @@
 ---
 layout: default
 title: "Architecture"
-nav_order: 5
+nav_order: 3
 description: "ColdBrew architecture: request lifecycle, interceptor chain, and package dependencies"
 permalink: /architecture
 ---
diff --git a/config-reference.md b/config-reference.md
@@ -1,7 +1,7 @@
 ---
 layout: default
 title: "Configuration Reference"
-nav_order: 5
+nav_order: 4
 description: "Complete environment variable reference for ColdBrew Go microservice framework configuration"
 permalink: /config-reference
 ---
diff --git a/howto/APIs.md b/howto/APIs.md
@@ -2,6 +2,7 @@
 layout: default
 title: "Building and Configuring APIs"
 parent: "How To"
+nav_order: 1
 description: "Build gRPC and REST APIs with ColdBrew using protobuf definitions and grpc-gateway HTTP annotations"
 ---
 ## Table of contents
diff --git a/howto/Debugging.md b/howto/Debugging.md
@@ -2,6 +2,7 @@
 layout: default
 title: "Debugging"
 parent: "How To"
+nav_order: 8
 description: "Debugging ColdBrew services with pprof and log overrides"
 ---
 ## Table of contents
diff --git a/howto/Log.md b/howto/Log.md
@@ -2,6 +2,7 @@
 layout: default
 title: "Log"
 parent: "How To"
+nav_order: 3
 description: "Context-aware logging and trace ID propagation in ColdBrew"
 ---
 ## Table of contents
diff --git a/howto/Metrics.md b/howto/Metrics.md
@@ -2,7 +2,8 @@
 layout: default
 title: "Metrics"
 parent: "How To"
-description: "Prometheus metrics and custom metrics in ColdBrew"
+nav_order: 6
+description: "Prometheus metrics and custom metrics in ColdBrew: default runtime metrics, custom counters and histograms, and Hystrix circuit breaker monitoring"
 ---
 ## Table of contents
 {: .no_toc .text-delta }
diff --git a/howto/Tracing.md b/howto/Tracing.md
@@ -2,6 +2,7 @@
 layout: default
 title: "Tracing"
 parent: "How To"
+nav_order: 5
 description: "Set up distributed tracing in ColdBrew with OpenTelemetry and New Relic for gRPC services"
 ---
 ## Table of contents
diff --git a/howto/data-builder.md b/howto/data-builder.md
@@ -2,6 +2,7 @@
 layout: default
 title: "Data Builder"
 parent: "How To"
+nav_order: 11
 description: "How to use go-coldbrew/data-builder package to orchestrate data-processing logic in Go."
 ---
 ## Table of contents
diff --git a/howto/errors.md b/howto/errors.md
@@ -2,6 +2,7 @@
 layout: default
 title: "Errors"
 parent: "How To"
+nav_order: 4
 description: "How to use go-coldbrew/errors package to handle errors in Go."
 ---
 ## Table of contents
diff --git a/howto/gRPC.md b/howto/gRPC.md
@@ -2,7 +2,8 @@
 layout: default
 title: "gRPC"
 parent: "How To"
-description: "How to use gRPC with ColdBrew"
+nav_order: 2
+description: "How to use gRPC with ColdBrew: connection pooling, client setup with grpcpool, and building gRPC-first microservices in Go"
 ---
 ## Table of contents
 {: .no_toc .text-delta }
diff --git a/howto/index.md b/howto/index.md
@@ -1,7 +1,7 @@
 ---
 layout: default
 title: How To
-nav_order: 6
+nav_order: 5
 description: "Step-by-step guides for logging, tracing, metrics, error handling, APIs, and debugging in ColdBrew Go services"
 permalink: /howto
 has_children: true
diff --git a/howto/interceptors.md b/howto/interceptors.md
@@ -2,6 +2,7 @@
 layout: default
 title: "Interceptors"
 parent: "How To"
+nav_order: 7
 description: "Configuring gRPC interceptors in ColdBrew"
 ---
 ## Table of contents
diff --git a/howto/private-modules.md b/howto/private-modules.md
@@ -2,6 +2,7 @@
 layout: default
 title: "Private Modules"
 parent: "How To"
+nav_order: 16
 description: "Configure Go private modules for GitHub and GitLab private repositories in ColdBrew services"
 ---
 ## Table of contents
diff --git a/howto/production.md b/howto/production.md
@@ -2,6 +2,7 @@
 layout: default
 title: "Production Deployment"
 parent: "How To"
+nav_order: 13
 description: "Deploy ColdBrew Go services to production with Kubernetes manifests, health probes, Prometheus, distributed tracing, and graceful shutdown"
 ---
 ## Table of contents
diff --git a/howto/signals.md b/howto/signals.md
@@ -2,6 +2,7 @@
 layout: default
 title: "Signal Handling and Graceful Shutdown"
 parent: "How To"
+nav_order: 9
 description: "How POSIX signal handling works in ColdBrew"
 ---
 ## Table of contents
diff --git a/howto/swagger.md b/howto/swagger.md
@@ -2,6 +2,7 @@
 layout: default
 title: "Swagger / Open API Support"
 parent: "How To"
+nav_order: 10
 description: "How ColdBrew supports Swagger / Open API"
 ---
 ## Table of contents
diff --git a/howto/testing.md b/howto/testing.md
@@ -2,6 +2,7 @@
 layout: default
 title: "Testing"
 parent: "How To"
+nav_order: 14
 description: "Unit tests, mocks, benchmarks, and coverage reports in ColdBrew services"
 ---
 ## Table of contents
diff --git a/howto/vtproto.md b/howto/vtproto.md
@@ -2,6 +2,7 @@
 layout: default
 title: "VTProtobuf (Fast Serialization)"
 parent: "How To"
+nav_order: 12
 description: "How ColdBrew uses vtprotobuf for faster gRPC serialization with automatic fallback to standard protobuf"
 ---
 ## Table of contents
diff --git a/howto/workers.md b/howto/workers.md
diff --git a/integrations.md b/integrations.md
diff --git a/robots.txt b/robots.txt
diff --git a/tests/content.spec.ts b/tests/content.spec.ts
