docs(site): show release version and github stars

docs/.vitepress/config.mts

@@ -1,3 +1,6 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import { defineConfig } from "vitepress";
 import spec from "../cli/reference/commands.json";
 import kdlGrammar from "./grammars/kdl.tmLanguage.json";
@@ -13,6 +16,13 @@ function getCommands(cmd): string[][] {
 }
 
 const commands = getCommands(spec.cmd);
+const configDir = dirname(fileURLToPath(import.meta.url));
+const cargoToml = readFileSync(resolve(configDir, "../../lib/Cargo.toml"), "utf8");
+const versionMatch = cargoToml.match(/^\[package\][\s\S]*?^\s*version\s*=\s*"([^"]+)"/m);
+if (!versionMatch) {
+  console.warn("Unable to find package version in lib/Cargo.toml");
+}
+const latestVersion = versionMatch?.[1] ?? "0.0.0";
 
 // https://vitepress.dev/reference/site-config
 export default defineConfig({
@@ -36,7 +46,7 @@ export default defineConfig({
       { text: "Home", link: "/" },
       { text: "Spec", link: "/spec/" },
       { text: "CLI", link: "/cli/" },
-      { text: "Releases", link: "https://github.com/jdx/usage/releases" }
+      { text: `v${latestVersion}`, link: "https://github.com/jdx/usage/releases" }
     ],
 
     sidebar: [

docs/.vitepress/stars.data.ts

@@ -0,0 +1,41 @@
+const fallbackStars = 0;
+
+function formatStars(stars: number) {
+  if (stars < 1000) return String(stars);
+  return `${(stars / 1000).toFixed(1).replace(/\.0$/, "")}k`;
+}
+
+export default {
+  async load() {
+    const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
+    const shouldUpdate = token || process.env.UPDATE_GITHUB_STARS === "1";
+    let stars = fallbackStars;
+
+    if (shouldUpdate) {
+      try {
+        const headers: Record<string, string> = {
+          "User-Agent": "usage-docs",
+          Accept: "application/vnd.github+json",
+        };
+        if (token) headers.Authorization = `Bearer ${token}`;
+
+        const response = await fetch("https://api.github.com/repos/jdx/usage", {
+          headers,
+          signal: AbortSignal.timeout(10000),
+        });
+        if (response.ok) {
+          const data = (await response.json()) as { stargazers_count?: number };
+          if (typeof data.stargazers_count === "number") {
+            stars = data.stargazers_count;
+          }
+        }
+      } catch {
+        // Keep docs builds working offline or when GitHub rate limits the request.
+      }
+    }
+
+    return {
+      stars: stars > 0 ? formatStars(stars) : "",
+    };
+  },
+};

docs/.vitepress/theme/custom.css

@@ -337,3 +337,44 @@
     max-width: 320px;
   }
 }
+
+.VPSocialLinks a[href*="github.com/jdx/usage"] {
+  display: inline-flex !important;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 0;
+  position: relative;
+  padding-bottom: 12px !important;
+  margin-bottom: -12px !important;
+}
+
+.VPSocialLinks a[href*="github.com/jdx/usage"] svg {
+  display: block !important;
+  width: 20px;
+  height: 20px;
+  margin-top: 2px;
+}
+
+.VPSocialLinks .star-count {
+  position: absolute;
+  bottom: 0;
+  left: 50%;
+  transform: translateX(-50%);
+  font-size: 0.6rem;
+  font-weight: 600;
+  color: var(--vp-c-text-3);
+  font-family: var(--vp-font-family-mono);
+  white-space: nowrap;
+  line-height: 1;
+}
+
+.VPSocialLinks a[href*="github.com/jdx/usage"]:hover .star-count {
+  color: var(--vp-c-brand-1);
+}
+
+@media (max-width: 640px) {
+  .VPSocialLinks .star-count {
+    display: none;
+  }
+}

docs/.vitepress/theme/index.ts

@@ -1,8 +1,9 @@
 import DefaultTheme from 'vitepress/theme'
-import { h } from 'vue'
+import { h, onMounted, onUnmounted } from 'vue'
 import UsageHero from './UsageHero.vue'
 import EndevFooter from './EndevFooter.vue'
 import { initBanner } from './banner'
+import { data as starsData } from '../stars.data'
 import './custom.css'
 
 export default {
@@ -15,5 +16,35 @@ export default {
   },
   enhanceApp() {
     initBanner()
+  },
+  setup() {
+    let observer: MutationObserver | undefined
+    onMounted(() => {
+      const addStarCount = () => {
+        if (!starsData.stars) return false
+
+        const githubLinks = document.querySelectorAll(
+          '.VPSocialLinks a[href*="github.com/jdx/usage"]',
+        )
+        githubLinks.forEach((githubLink) => {
+          if (!githubLink.querySelector('.star-count')) {
+            const starBadge = document.createElement('span')
+            starBadge.className = 'star-count'
+            starBadge.textContent = starsData.stars
+            starBadge.title = 'GitHub Stars'
+            githubLink.appendChild(starBadge)
+          }
+        })
+        return githubLinks.length > 0 && Array.from(githubLinks).every((link) => link.querySelector('.star-count'))
+      }
+
+      if (addStarCount()) return
+
+      observer = new MutationObserver(() => {
+        if (addStarCount()) observer?.disconnect()
+      })
+      observer.observe(document.querySelector('.VPNav') || document.body, { childList: true, subtree: true })
+    })
+    onUnmounted(() => observer?.disconnect())
   }
 }