fix(docs): address PR review + live GitHub star count

vishr · claude · vishr · commit 7bedf330df7a · 2026-06-15T08:04:24.000-07:00
Review fixes (site/):
- editLink baseUrl pointed at website/, now site/ (Edit-page links were wrong)
- wrap dark-first localStorage script in try/catch (no private-mode throw/FOUC)
- AskEcho: null-guard DOM lookups + early-return logging, clear pending timeout,
  add "Demo - not connected" label, fix stub echo-jwt v4 -&gt; v5
- make content `description` schema-required (build-enforced; used for SEO/OG)
- add target=_blank rel=noopener noreferrer to external homepage links

Live GitHub stars:
- fetch star count at build time (src/data/github.ts) with graceful fallback;
  dedupe the two hardcoded "32.4k" spots to this single source
- add daily schedule cron + workflow_dispatch + authenticated GITHUB_TOKEN to the
  deploy workflow so the count refreshes without manual deploys

Co-Authored-By: Claude Opus 4.8 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/.github/workflows/deploy.yaml b/.github/workflows/deploy.yaml
@@ -4,8 +4,12 @@ on:
   push:
     branches:
       - master
-    # Review gh actions docs if you want to further define triggers, paths, etc
-    # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on
+  # Daily rebuild so build-time data — e.g. the GitHub star count fetched in the
+  # Astro site's src/data/github.ts — stays fresh without a manual deploy.
+  schedule:
+    - cron: '0 6 * * *'
+  # Allow manual runs from the Actions tab.
+  workflow_dispatch:
 
 jobs:
   deploy:
@@ -25,6 +29,9 @@ jobs:
       - name: Build website
         run: npm run build
         working-directory: website
+        env:
+          # Lifts the GitHub API rate limit for build-time stats fetches.
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
 
       # Popular action to deploy to GitHub Pages:
       # Docs: https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-docusaurus
diff --git a/site/astro.config.mjs b/site/astro.config.mjs
@@ -17,7 +17,7 @@ export default defineConfig({
         { icon: 'github', label: 'GitHub', href: 'https://github.com/labstack/echo' },
       ],
       editLink: {
-        baseUrl: 'https://github.com/labstack/echox/edit/master/website/',
+        baseUrl: 'https://github.com/labstack/echox/edit/master/site/',
       },
       lastUpdated: true,
       // Echo "E" cube mark; .ico kept as legacy fallback, apple-touch-icon added in head.
@@ -31,7 +31,7 @@ export default defineConfig({
         // Dark-first: default new visitors to dark unless they've chosen otherwise.
         {
           tag: 'script',
-          content: "if(!localStorage.getItem('starlight-theme')){localStorage.setItem('starlight-theme','dark');document.documentElement.dataset.theme='dark';}",
+          content: "try{if(!localStorage.getItem('starlight-theme')){localStorage.setItem('starlight-theme','dark');document.documentElement.dataset.theme='dark';}}catch(e){document.documentElement.dataset.theme='dark';}",
         },
         { tag: 'link', attrs: { rel: 'preconnect', href: 'https://fonts.googleapis.com' } },
         { tag: 'link', attrs: { rel: 'preconnect', href: 'https://fonts.gstatic.com', crossorigin: true } },
diff --git a/site/src/components/AskEcho.astro b/site/src/components/AskEcho.astro
@@ -1,5 +1,8 @@
 ---
 // Vanilla Astro island — no React. Fab + ⌘-style modal with a (stubbed) streamed answer.
+// NOTE: the answer is a hardcoded DEMO, not a live model. To connect a real provider,
+// replace the timer block in ask() with a fetch (see website/src/components/AskEcho.js
+// for a kapa.ai-style sketch).
 const SUGGESTIONS = [
   { icon: 'ph-lock-key', q: 'How do I add JWT authentication?' },
   { icon: 'ph-globe', q: 'How do I enable CORS?' },
@@ -23,68 +26,85 @@ const SUGGESTIONS = [
         {SUGGESTIONS.map((s) => (
           <button class="ask-s" data-q={s.q} type="button"><i class={`ph ${s.icon}`}></i> {s.q}</button>
         ))}
+        <p class="ask-demo">Demo — answers are illustrative and not yet connected to a live model.</p>
       </div>
     </div>
   </div>
 </div>
 
+<style>
+  .ask-demo { margin: 16px 4px 2px; font-size: 0.72rem; line-height: 1.5; color: var(--sl-color-gray-4); font-family: var(--sl-font-mono); }
+</style>
+
 <script>
-  const fab = document.getElementById('ask-fab')!;
-  const overlay = document.getElementById('ask-overlay')!;
-  const input = document.getElementById('ask-input') as HTMLInputElement;
-  const body = document.getElementById('ask-body')!;
-  // Portal to <body> so position:fixed + z-index escape any Starlight stacking context.
-  document.body.appendChild(fab);
-  document.body.appendChild(overlay);
-  const suggestHTML = body.innerHTML;
-  let timer: ReturnType<typeof setInterval> | undefined;
+  function initAskEcho() {
+    const fab = document.getElementById('ask-fab');
+    const overlay = document.getElementById('ask-overlay');
+    const input = document.getElementById('ask-input') as HTMLInputElement | null;
+    const body = document.getElementById('ask-body');
+    if (!fab || !overlay || !input || !body) {
+      console.error('[AskEcho] missing required DOM nodes; island not initialized');
+      return;
+    }
+    // Portal to <body> so position:fixed + z-index escape any Starlight stacking context.
+    document.body.appendChild(fab);
+    document.body.appendChild(overlay);
+    const suggestHTML = body.innerHTML;
+    let timer: ReturnType<typeof setInterval> | undefined;
+    let pending: ReturnType<typeof setTimeout> | undefined;
 
-  const ANSWER =
-    `To add JWT authentication, use Echo's built-in <strong>JWT middleware</strong>. Register it on the routes (or group) you want to protect:\n\n<pre>import echojwt "github.com/labstack/echo-jwt/v4"\n\ne.Use(echojwt.WithConfig(echojwt.Config{\n    SigningKey: []byte("your-secret"),\n}))</pre>\n\nRequests must then send <code>Authorization: Bearer &lt;token&gt;</code>. Read claims with <code>c.Get("user")</code>.`;
-  const SOURCES = ['Guide › Middleware › JWT', 'Cookbook › JWT Authentication', 'API › echo-jwt'];
+    // Hardcoded DEMO answer — swap the timer block in ask() for a real provider fetch.
+    const ANSWER =
+      `To add JWT authentication, use Echo's built-in <strong>JWT middleware</strong>. Register it on the routes (or group) you want to protect:\n\n<pre>import echojwt "github.com/labstack/echo-jwt/v5"\n\ne.Use(echojwt.WithConfig(echojwt.Config{\n    SigningKey: []byte("your-secret"),\n}))</pre>\n\nRequests must then send <code>Authorization: Bearer &lt;token&gt;</code>. Read claims with <code>c.Get("user")</code>.`;
+    const SOURCES = ['Guide › Middleware › JWT', 'Cookbook › JWT Authentication', 'API › echo-jwt'];
 
-  function bindSuggest() {
-    body.querySelectorAll<HTMLButtonElement>('.ask-s').forEach((b) =>
-      b.addEventListener('click', () => ask(b.dataset.q || ''))
-    );
-  }
-  function open() {
-    overlay.hidden = false; fab.hidden = true;
-    body.innerHTML = suggestHTML; bindSuggest(); input.value = '';
-    setTimeout(() => input.focus(), 40);
-  }
-  function close() {
-    overlay.hidden = true; fab.hidden = false;
-    if (timer) clearInterval(timer);
-  }
-  function sourcesHTML() {
-    return '<div class="ask-sources"><h5>Sources</h5>' +
-      SOURCES.map((s, i) => `<div class="ask-src"><span class="ask-n">${i + 1}</span> ${s}</div>`).join('') +
-      '</div>';
-  }
-  function ask(q: string) {
-    input.value = q;
-    body.innerHTML = '<div class="ask-badge"><span class="ask-dot"></span> Ask Echo is thinking…</div><div class="ask-answer" id="ask-ans"></div>';
-    const ans = document.getElementById('ask-ans')!;
-    setTimeout(() => {
-      ans.parentElement!.querySelector('.ask-badge')!.innerHTML = '<span class="ask-dot"></span> Ask Echo';
-      let i = 0;
-      timer = setInterval(() => {
-        i += 5;
-        ans.innerHTML = ANSWER.slice(0, i).replace(/\n/g, '<br/>') + '<span class="ask-cursor"></span>';
-        if (i >= ANSWER.length) {
-          if (timer) clearInterval(timer);
-          ans.innerHTML = ANSWER.replace(/\n/g, '<br/>');
-          ans.insertAdjacentHTML('beforeend', sourcesHTML());
-        }
-      }, 12);
-    }, 420);
-  }
+    function bindSuggest() {
+      body.querySelectorAll<HTMLButtonElement>('.ask-s').forEach((b) =>
+        b.addEventListener('click', () => ask(b.dataset.q || ''))
+      );
+    }
+    function open() {
+      overlay.hidden = false; fab.hidden = true;
+      body.innerHTML = suggestHTML; bindSuggest(); input.value = '';
+      setTimeout(() => input.focus(), 40);
+    }
+    function close() {
+      overlay.hidden = true; fab.hidden = false;
+      if (timer) clearInterval(timer);
+      if (pending) clearTimeout(pending);
+    }
+    function sourcesHTML() {
+      return '<div class="ask-sources"><h5>Sources</h5>' +
+        SOURCES.map((s, i) => `<div class="ask-src"><span class="ask-n">${i + 1}</span> ${s}</div>`).join('') +
+        '</div>';
+    }
+    function ask(q: string) {
+      input.value = q;
+      body.innerHTML = '<div class="ask-badge"><span class="ask-dot"></span> Ask Echo is thinking…</div><div class="ask-answer" id="ask-ans"></div>';
+      const ans = document.getElementById('ask-ans');
+      if (!ans) return;
+      pending = setTimeout(() => {
+        const badge = ans.parentElement?.querySelector('.ask-badge');
+        if (badge) badge.innerHTML = '<span class="ask-dot"></span> Ask Echo';
+        let i = 0;
+        timer = setInterval(() => {
+          i += 5;
+          ans.innerHTML = ANSWER.slice(0, i).replace(/\n/g, '<br/>') + '<span class="ask-cursor"></span>';
+          if (i >= ANSWER.length) {
+            if (timer) clearInterval(timer);
+            ans.innerHTML = ANSWER.replace(/\n/g, '<br/>');
+            ans.insertAdjacentHTML('beforeend', sourcesHTML());
+          }
+        }, 12);
+      }, 420);
+    }
 
-  bindSuggest();
-  fab.addEventListener('click', open);
-  window.addEventListener('ask-echo-open', open);
-  overlay.addEventListener('mousedown', (e) => { if (e.target === overlay) close(); });
-  input.addEventListener('keydown', (e) => { if (e.key === 'Enter' && input.value.trim()) ask(input.value.trim()); });
-  window.addEventListener('keydown', (e) => { if (e.key === 'Escape') close(); });
+    bindSuggest();
+    fab.addEventListener('click', open);
+    window.addEventListener('ask-echo-open', open);
+    overlay.addEventListener('mousedown', (e) => { if (e.target === overlay) close(); });
+    input.addEventListener('keydown', (e) => { if (e.key === 'Enter' && input.value.trim()) ask(input.value.trim()); });
+    window.addEventListener('keydown', (e) => { if (e.key === 'Escape') close(); });
+  }
+  initAskEcho();
 </script>
diff --git a/site/src/components/HomeHero.astro b/site/src/components/HomeHero.astro
@@ -2,6 +2,7 @@
 // Living Terminal hero: code window + a terminal pane that types `curl`
 // and streams Echo's JSON response. Animation is client-side, with a
 // static final-state fallback for reduced-motion / no-JS.
+import { starsLabel } from '../data/github.ts';
 ---
 
 <section class="hh">
@@ -15,7 +16,7 @@
     </p>
     <div class="hh-cta">
       <a class="hh-btn pri" href="/guide/quickstart/">Get Started <i class="ph ph-arrow-right"></i></a>
-      <a class="hh-btn sec" href="https://github.com/labstack/echo"><i class="ph ph-star"></i> 32.4k on GitHub</a>
+      <a class="hh-btn sec" href="https://github.com/labstack/echo" target="_blank" rel="noopener noreferrer"><i class="ph ph-star"></i> {starsLabel} on GitHub</a>
     </div>
     <button class="hh-install" type="button" data-copy="go get github.com/labstack/echo/v5" aria-label="Copy install command">
       <span class="p">$</span> go get github.com/labstack/echo/v5 <i class="ph ph-copy cp"></i>
diff --git a/site/src/content.config.ts b/site/src/content.config.ts
@@ -1,7 +1,13 @@
 import { defineCollection } from 'astro:content';
 import { docsLoader } from '@astrojs/starlight/loaders';
 import { docsSchema } from '@astrojs/starlight/schema';
+import { z } from 'astro:schema';
 
 export const collections = {
-  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
+  docs: defineCollection({
+    loader: docsLoader(),
+    // `description` is required (not optional as in the stock schema): every page uses it
+    // for SEO/OG meta, so enforce it at build time rather than by convention.
+    schema: docsSchema({ extend: z.object({ description: z.string().min(1) }) }),
+  }),
 };
diff --git a/site/src/content/docs/index.mdx b/site/src/content/docs/index.mdx
@@ -15,11 +15,12 @@ tableOfContents: false
 ---
 
 import HomeHero from '../../components/HomeHero.astro';
+import { starsLabel } from '../../data/github.ts';
 
 <HomeHero />
 
 <div class="echo-stats">
-  <div><b>32.4k</b><span>GitHub stars</span></div>
+  <div><b>{starsLabel}</b><span>GitHub stars</span></div>
   <div><b>0 allocs</b><span>router, per request</span></div>
   <div><b>25+</b><span>built-in middlewares</span></div>
   <div><b>MIT</b><span>open source license</span></div>
@@ -50,27 +51,27 @@ e.Start(":1323")</pre></div>
 <div class="echo-h"><span class="ey">Ecosystem</span><h2>Official packages, ready to plug in.</h2></div>
 
 <div class="echo-eco">
-  <a class="eco-card" href="https://github.com/labstack/echo-jwt"><h4>echo-jwt</h4><p>JWT authentication middleware backed by golang-jwt.</p></a>
-  <a class="eco-card" href="https://github.com/labstack/echo-contrib"><h4>echo-contrib</h4><p>Prometheus, Casbin, Jaeger, pprof, Zipkin &amp; session helpers.</p></a>
-  <a class="eco-card" href="https://github.com/swaggo/echo-swagger"><h4>echo-swagger</h4><p>Generate and serve interactive Swagger / OpenAPI docs.</p></a>
-  <a class="eco-card" href="https://pkg.go.dev/github.com/labstack/echo/v5"><h4>API Reference</h4><p>Full package documentation on pkg.go.dev.</p></a>
+  <a class="eco-card" href="https://github.com/labstack/echo-jwt" target="_blank" rel="noopener noreferrer"><h4>echo-jwt</h4><p>JWT authentication middleware backed by golang-jwt.</p></a>
+  <a class="eco-card" href="https://github.com/labstack/echo-contrib" target="_blank" rel="noopener noreferrer"><h4>echo-contrib</h4><p>Prometheus, Casbin, Jaeger, pprof, Zipkin &amp; session helpers.</p></a>
+  <a class="eco-card" href="https://github.com/swaggo/echo-swagger" target="_blank" rel="noopener noreferrer"><h4>echo-swagger</h4><p>Generate and serve interactive Swagger / OpenAPI docs.</p></a>
+  <a class="eco-card" href="https://pkg.go.dev/github.com/labstack/echo/v5" target="_blank" rel="noopener noreferrer"><h4>API Reference</h4><p>Full package documentation on pkg.go.dev.</p></a>
 </div>
 
 <div class="echo-h"><span class="ey">Sponsors</span><h2>Backed by teams who build on Echo.</h2></div>
 
-<a class="sp-featured" href="https://encore.dev">
+<a class="sp-featured" href="https://encore.dev" target="_blank" rel="noopener noreferrer">
   <img src="https://github.com/encoredev.png?size=88" alt="Encore" />
   <span class="t"><b>Encore</b><span>The platform for building Go-based cloud backends.</span></span>
 </a>
 
 <div class="sp-grid">
-  <a class="sp-card" href="https://github.com/customerio"><img src="https://github.com/customerio.png?size=52" alt="Customer.io" /><span>Customer.io</span></a>
-  <a class="sp-card" href="https://github.com/gravitycarbon"><img src="https://github.com/gravitycarbon.png?size=52" alt="Gravity Carbon" /><span>Gravity Carbon</span></a>
-  <a class="sp-card" href="https://github.com/mjslabs"><img src="https://github.com/mjslabs.png?size=52" alt="MJS Labs" /><span>MJS Labs</span></a>
-  <a class="sp-card" href="https://github.com/Codeerror"><img src="https://github.com/Codeerror.png?size=52" alt="Codeerror" /><span>Codeerror</span></a>
+  <a class="sp-card" href="https://github.com/customerio" target="_blank" rel="noopener noreferrer"><img src="https://github.com/customerio.png?size=52" alt="Customer.io" /><span>Customer.io</span></a>
+  <a class="sp-card" href="https://github.com/gravitycarbon" target="_blank" rel="noopener noreferrer"><img src="https://github.com/gravitycarbon.png?size=52" alt="Gravity Carbon" /><span>Gravity Carbon</span></a>
+  <a class="sp-card" href="https://github.com/mjslabs" target="_blank" rel="noopener noreferrer"><img src="https://github.com/mjslabs.png?size=52" alt="MJS Labs" /><span>MJS Labs</span></a>
+  <a class="sp-card" href="https://github.com/Codeerror" target="_blank" rel="noopener noreferrer"><img src="https://github.com/Codeerror.png?size=52" alt="Codeerror" /><span>Codeerror</span></a>
 </div>
 
-<div class="sp-cta"><a href="https://github.com/sponsors/labstack"><i class="ph ph-heart"></i> Become a sponsor</a></div>
+<div class="sp-cta"><a href="https://github.com/sponsors/labstack" target="_blank" rel="noopener noreferrer"><i class="ph ph-heart"></i> Become a sponsor</a></div>
 
 <div class="echo-foot">
   <div class="brand">
@@ -86,15 +87,15 @@ e.Start(":1323")</pre></div>
   </div>
   <div class="col">
     <h4>Project</h4>
-    <a href="https://github.com/labstack/echo">GitHub</a>
-    <a href="https://github.com/labstack/echo/releases">Releases</a>
-    <a href="https://github.com/labstack/echo/discussions">Discussions</a>
-    <a href="https://github.com/labstack/echo/blob/master/.github/CONTRIBUTING.md">Contributing</a>
+    <a href="https://github.com/labstack/echo" target="_blank" rel="noopener noreferrer">GitHub</a>
+    <a href="https://github.com/labstack/echo/releases" target="_blank" rel="noopener noreferrer">Releases</a>
+    <a href="https://github.com/labstack/echo/discussions" target="_blank" rel="noopener noreferrer">Discussions</a>
+    <a href="https://github.com/labstack/echo/blob/master/.github/CONTRIBUTING.md" target="_blank" rel="noopener noreferrer">Contributing</a>
   </div>
   <div class="col">
     <h4>Resources</h4>
-    <a href="https://pkg.go.dev/github.com/labstack/echo/v5">API Reference</a>
-    <a href="https://github.com/sponsors/labstack">Sponsor</a>
-    <a href="https://github.com/labstack/echo/blob/master/LICENSE">MIT License</a>
+    <a href="https://pkg.go.dev/github.com/labstack/echo/v5" target="_blank" rel="noopener noreferrer">API Reference</a>
+    <a href="https://github.com/sponsors/labstack" target="_blank" rel="noopener noreferrer">Sponsor</a>
+    <a href="https://github.com/labstack/echo/blob/master/LICENSE" target="_blank" rel="noopener noreferrer">MIT License</a>
   </div>
 </div>
diff --git a/site/src/data/github.ts b/site/src/data/github.ts
@@ -0,0 +1,31 @@
+// Build-time GitHub stats. Fetched once during `astro build` and inlined into the
+// static HTML — no client JS, no runtime rate limits. The daily deploy cron
+// (.github/workflows/deploy.yaml) re-runs the build so the number stays fresh.
+// Falls back gracefully so an offline / rate-limited build never fails.
+const REPO = 'labstack/echo';
+const FALLBACK_STARS = 32400;
+
+async function fetchStars(): Promise<number> {
+  try {
+    const headers: Record<string, string> = {
+      Accept: 'application/vnd.github+json',
+      'User-Agent': 'echo-docs-build',
+    };
+    // Optional: set GITHUB_TOKEN in CI to lift the 60 req/hr unauthenticated limit.
+    const token = process.env.GITHUB_TOKEN;
+    if (token) headers.Authorization = `Bearer ${token}`;
+
+    const res = await fetch(`https://api.github.com/repos/${REPO}`, { headers });
+    if (!res.ok) throw new Error(`GitHub API responded ${res.status}`);
+    const data = await res.json();
+    return typeof data.stargazers_count === 'number' ? data.stargazers_count : FALLBACK_STARS;
+  } catch (e) {
+    console.warn(`[github] star fetch failed; using fallback ${FALLBACK_STARS}:`, e);
+    return FALLBACK_STARS;
+  }
+}
+
+export const stars = await fetchStars();
+
+/** e.g. 32412 -> "32.4k" */
+export const starsLabel = stars >= 1000 ? `${(stars / 1000).toFixed(1)}k` : String(stars);
