Skip to content

feat: render GitHub issue/PR links GitHub-style with state + title#19

Open
16bit-ykiko wants to merge 1 commit into
mainfrom
feat/github-link-rendering
Open

feat: render GitHub issue/PR links GitHub-style with state + title#19
16bit-ykiko wants to merge 1 commit into
mainfrom
feat/github-link-rendering

Conversation

@16bit-ykiko

Copy link
Copy Markdown
Member

Summary

Bare GitHub issue/PR URLs in the docs now render the way GitHub renders a pasted reference, instead of as a plain link:

  • a state-colored octicon leads the link (open = green, closed/merged = purple, closed-PR = red, not-planned = gray; PRs get the git-pull-request glyph);
  • the issue/PR title is shown inline (backtick spans become inline <code>);
  • a muted owner/repo#number trails the title.

This replaces the previous hand-maintained `open`/`closed` markers in footnotes — authors now just drop a bare GitHub URL and the state + title render automatically.

How it works

  • A markdown-it plugin (.vitepress/github-links.ts) rewrites matching issue/PR links at render time and is wired into config.mts.
  • Issue/PR state + title are resolved at build time and cached in .vitepress/github-links.json, so the published site is a static snapshot with no client-side API calls.
  • The cache refreshes live only when GITHUB_TOKEN/GH_TOKEN is present (CI) or DOCS_REFRESH_GH=1 is set; otherwise local builds stay fully offline and deterministic (no rate limits).
  • Explicit markdown links (e.g. changelog [#460](url)) keep the author's text and only gain the leading state icon.

Test plan

  • npm run build succeeds (verified locally).
  • Footnote-heavy feature pages render [icon] Title owner/repo#number inline (verified via headless screenshot of features/completion).
  • Backtick spans in titles render as inline code (e.g. clangd#2626 → import, module, CompletionItemKind.Keyword).
  • Icon size/alignment matches surrounding text.
  • No live API calls on a tokenless build (offline cache used).

Bare GitHub issue/PR URLs in markdown now render the way GitHub renders a
pasted reference: a leading state-colored octicon, the issue/PR title
inline (backtick spans become inline code), and a muted owner/repo#number.

State and title are resolved at build time and cached in
.vitepress/github-links.json, so the published site is a static snapshot
with no client-side API calls. The cache refreshes live only when a
GITHUB_TOKEN is present or DOCS_REFRESH_GH=1 is set; otherwise builds stay
fully offline and deterministic.
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