Skip to content

docs(site): show release version and github stars#872

Merged
jdx merged 2 commits intomainfrom
codex/release-version-title
Apr 25, 2026
Merged

docs(site): show release version and github stars#872
jdx merged 2 commits intomainfrom
codex/release-version-title

Conversation

@jdx
Copy link
Copy Markdown
Owner

@jdx jdx commented Apr 25, 2026

Summary

  • read the latest site release label from Cargo.toml and show it as the releases nav item
  • add a GitHub star counter to the VitePress social nav, matching the existing aube/mise pattern

Validation

  • npm run docs:build in /home/jdx/src/hk-release-version/docs

Note: local git hooks were skipped for commit/push because the fresh worktree hook config could not evaluate pkl/Builtins.pkl; the targeted docs build passed.

This PR was generated by Codex.


Note

Low Risk
Low risk docs-only changes, but adds build-time parsing of Cargo.toml and an optional GitHub API call that could affect docs builds if environment/network assumptions change.

Overview
Updates the VitePress docs nav to show the current release label (e.g. vX.Y.Z) by parsing Cargo.toml at build time, replacing the static “Releases” text.

Adds an optional GitHub star counter: stars.data.ts can fetch stargazers_count from the GitHub API (gated by env vars/tokens and tolerant of offline/rate limits), and the theme injects/stylizes a .star-count badge onto the GitHub social link using a MutationObserver for late-rendered DOM.

Reviewed by Cursor Bugbot for commit 7235569. Bugbot is set up for automated code reviews on this repo. Configure here.

Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request automates the version display in the documentation by reading the version from Cargo.toml and introduces a dynamic GitHub star count badge in the social links. Feedback was provided to optimize the DOM manipulation logic for the star count, suggesting the use of querySelectorAll and a more focused MutationObserver scope to improve performance and ensure the badge appears in all navigation contexts.

Comment thread docs/.vitepress/theme/index.ts Outdated
Comment on lines +19 to +35
const addStarCount = () => {
const githubLink = document.querySelector(
'.VPSocialLinks a[href*="github.com/jdx/hk"]',
)
if (githubLink && !githubLink.querySelector('.star-count')) {
const starBadge = document.createElement('span')
starBadge.className = 'star-count'
starBadge.textContent = starsData.stars
starBadge.title = 'GitHub Stars'
githubLink.appendChild(starBadge)
}
}

addStarCount()
setTimeout(addStarCount, 100)
const observer = new MutationObserver(addStarCount)
observer.observe(document.body, { childList: true, subtree: true })
Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Using MutationObserver on document.body with subtree: true can have a negative impact on performance as it triggers on every DOM change across the entire page. Additionally, document.querySelector only targets the first matching element, which might miss the social links in the mobile navigation if both desktop and mobile navs are present in the DOM.

Consider using querySelectorAll to update all instances and narrowing the observer's scope to the navigation bar (.VPNav) for better efficiency. The setTimeout is also likely redundant if the observer is correctly configured.

      const addStarCount = () => {
        const githubLinks = document.querySelectorAll(
          '.VPSocialLinks a[href*="github.com/jdx/hk"]',
        )
        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)
          }
        })
      }

      addStarCount()
      const nav = document.querySelector('.VPNav')
      const observer = new MutationObserver(addStarCount)
      observer.observe(nav || document.body, { childList: true, subtree: true })

@greptile-apps
Copy link
Copy Markdown

greptile-apps Bot commented Apr 25, 2026

Greptile Summary

This PR updates the VitePress docs to surface two pieces of repo metadata: the nav bar now shows the current release version parsed from Cargo.toml at build time, and a GitHub star counter badge is appended to the social nav link at runtime via a MutationObserver. Both previously-flagged issues (hardcoded fallback stars and the uncleared observer) are resolved in this revision.

Confidence Score: 5/5

Safe to merge — docs-only change with no runtime or security impact on the tool itself.

No P0 or P1 issues found. Both previously flagged concerns (hardcoded fallback stars and uncleared MutationObserver) are resolved. The build-time Cargo.toml parsing has a graceful fallback, the GitHub API fetch is opt-in with a silent-catch, and the observer lifecycle is properly managed with onUnmounted.

No files require special attention.

Important Files Changed

Filename Overview
docs/.vitepress/config.mts Reads Cargo.toml at build time with a regex to extract version; gracefully falls back to '0.0.0' with a warning if the match fails. Path resolution and regex are correct for a standard (non-workspace) root Cargo.toml.
docs/.vitepress/stars.data.ts New VitePress data loader; fetches stargazers_count from GitHub API when a token or opt-in env var is present, returns empty string otherwise so no badge is shown in fallback mode. 10s AbortSignal timeout and silent catch make builds robust.
docs/.vitepress/theme/index.ts Injects star-count badge via MutationObserver in onMounted; observer is properly cleaned up in onUnmounted. Previous leak issue is resolved.
docs/.vitepress/theme/style.css Adds CSS for the star-count badge positioning and hover colour; uses !important to override VitePress defaults, hidden on small screens. Scoped tightly to the GitHub social link anchor.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    subgraph Build["Build Time (config.mts)"]
        A[Read Cargo.toml] --> B{Regex match /package/ version}
        B -- match --> C[latestVersion = semver]
        B -- no match --> D[latestVersion = '0.0.0' + console.warn]
        C --> E[Nav: vX.Y.Z → GitHub releases]
    end
    subgraph Stars["Build Time (stars.data.ts)"]
        F{GITHUB_TOKEN / UPDATE_GITHUB_STARS?}
        F -- yes --> G[GET api.github.com/repos/jdx/hk]
        G -- ok --> H[stars = stargazers_count]
        G -- error/timeout --> I[stars = 0 / empty string]
        F -- no --> I
        H --> J[return formatStars]
        I --> K[return empty string]
    end
    subgraph Runtime["Runtime (theme/index.ts)"]
        L[onMounted] --> M{starsData.stars not empty?}
        M -- yes --> N[querySelectorAll .VPSocialLinks]
        N -- found --> O[Append .star-count span]
        N -- not found --> P[MutationObserver watches .VPNav]
        P -- element appears --> O
        M -- empty --> Q[Observer watches but returns false immediately]
        O --> R[observer.disconnect]
        S[onUnmounted] --> T[observer?.disconnect]
    end
Loading

Reviews (2): Last reviewed commit: "docs(site): address release nav feedback" | Re-trigger Greptile

Comment thread docs/.vitepress/theme/index.ts Outdated
Comment thread docs/.vitepress/stars.data.ts Outdated
Comment thread docs/.vitepress/theme/index.ts Outdated
@jdx jdx marked this pull request as ready for review April 25, 2026 15:01
Copy link
Copy Markdown

@cursor cursor Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cursor Bugbot has reviewed your changes and found 1 potential issue.

Fix All in Cursor

❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.

Reviewed by Cursor Bugbot for commit 7235569. Configure here.

observer = new MutationObserver(() => {
if (addStarCount()) observer?.disconnect()
})
observer.observe(document.querySelector('.VPNav') || document.body, { childList: true, subtree: true })
Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

MutationObserver runs forever when stars data is empty

Low Severity

When starsData.stars is "" (the common case when no GITHUB_TOKEN or UPDATE_GITHUB_STARS env var is set during build), addStarCount() returns false immediately. The if (addStarCount()) return check at the outer level then falls through and creates a MutationObserver that can never disconnect — because every subsequent call to addStarCount() also returns false. This leaves a subtree observer permanently attached to .VPNav or document.body, firing its callback on every DOM mutation to no effect.

Additional Locations (1)
Fix in Cursor Fix in Web

Reviewed by Cursor Bugbot for commit 7235569. Configure here.

@jdx jdx merged commit 9a50d39 into main Apr 25, 2026
34 of 36 checks passed
@jdx jdx deleted the codex/release-version-title branch April 25, 2026 17:07
@jdx jdx mentioned this pull request Apr 25, 2026
jdx added a commit that referenced this pull request Apr 26, 2026
### 🐛 Bug Fixes

- **(builtins)** silence pklr deprecation warnings on Builtins.pkl load
by [@jdx](https://github.com/jdx) in
[#880](#880)
- **(ci)** serialize docs lint step by [@jdx](https://github.com/jdx) in
[#874](#874)
- **(config)** include main pkl path in cache fresh files by
[@jdx](https://github.com/jdx) in
[#879](#879)
- **(docs)** stack banner message and link on mobile by
[@jdx](https://github.com/jdx) in
[#865](#865)
- **(docs)** pin banner close button to top-right corner on mobile by
[@jdx](https://github.com/jdx) in
[#867](#867)

### 📚 Documentation

- **(site)** show release version and github stars by
[@jdx](https://github.com/jdx) in
[#872](#872)

### 🔍 Other Changes

- add pr-closer workflow by [@jdx](https://github.com/jdx) in
[#876](#876)

### 📦️ Dependency Updates

- bump communique 1.0.3 → 1.0.4 by [@jdx](https://github.com/jdx) in
[#868](#868)
- update anthropics/claude-code-action digest to 2da6cfa by
[@renovate[bot]](https://github.com/renovate[bot]) in
[#869](#869)
- update anthropics/claude-code-action digest to 567fe95 by
[@renovate[bot]](https://github.com/renovate[bot]) in
[#870](#870)
- bump communique to 1.1.2 by [@jdx](https://github.com/jdx) in
[#875](#875)

<!-- CURSOR_SUMMARY -->
---

> [!NOTE]
> <sup>[Cursor Bugbot](https://cursor.com/bugbot) is generating a
summary for commit 62ff432. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Co-authored-by: mise-en-dev <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant