GitHub Readme Stats

GitHub Readme Stats#

本文档介绍在 Sphinx 文档中使用 GitHub Readme Stats 的指令（模块：github_readme_stats），通过三条指令嵌入 GitHub Readme Stats 卡片：用户统计、常用语言、置顶仓库。

1.  快速开始#

在你的扩展入口或 conf.py 中注册指令：

extension = ["mystx.ext.github_readme_stats"]

2.  用法示例#

:::{github-stats}
:username: xinetzone
:theme: dark
:show_icons:
:hide: issues,contribs
:::
GitHub Stats
```{github-top-langs}
:username: xinetzone
:layout: compact
:theme: dark
:langs_count: 8
```
Top Languages
```{github-pinned-repo}
:username: xinetzone
:repo: mystx
:theme: dark
```
Pinned Repo
```{github-pinned-repo}
:username: xinetzone
:repo: tao
:theme: dark
:link: https://xinetzone.github.io/tao
```
Pinned Repo
:::{github-wakatime}
:username: xinetzone
:layout: compact
:theme: tokyonight
:range: all_time
:::
WakaTime Stats

3.  指令与选项说明#

3.1.  github-stats（用户统计卡片）#

  • username（必填）：GitHub 用户名。

  • theme（可选）：主题名称，默认 default。

  • show_icons（可选 flag）：出现该选项即显示图标。

  • hide（可选）：以逗号分隔的统计项列表，例如 issues,contribs。

上游可选项（需扩展）：

  • commits_year：指定年份统计提交数（格式 YYYY）。

  • show：展示额外统计项（逗号分隔）：reviews、discussions_started、discussions_answered、prs_merged、prs_merged_percentage。

  • include_all_commits：包含所有历史提交。

  • count_private：包含私有贡献统计。

  • hide_rank：隐藏等级环形标识。

  • rank_icon：等级图标样式（如 percentile）。

  • custom_title：自定义卡片标题。

  • hide_border：隐藏卡片边框。

  • card_width：卡片宽度（像素）。

  • locale：界面语言（如 zh-CN）。

  • 颜色与背景：text_color、title_color、icon_color、border_color、ring_color、bg_color（支持渐变：DEG,hex1,hex2）。

  • disable_animations：禁用卡片动画。

3.2.  github-top-langs（常用语言卡片）#

  • username（必填）：GitHub 用户名。

  • layout（可选）：布局样式，默认 compact。

  • theme（可选）：主题名称，默认 default。

  • langs_count（可选）：展示语言数量，默认 6。

上游可选项（需扩展）：

  • hide：隐藏指定语言（逗号分隔）。

  • exclude_repo：排除指定仓库（逗号分隔）。

  • card_width：卡片宽度（像素）。

  • hide_progress：隐藏进度条。

  • 统计格式：切换显示格式（如百分比/字节大小）。

  • 扩展布局：donut、donut-vertical、pie 等。

3.3.  github-pinned-repo（置顶仓库卡片）#

  • username（必填）：GitHub 用户名。

  • repo（必填）：仓库名。

  • theme（可选）：主题名称，默认 default。

  • link（可选）：点击卡片跳转的链接地址。

上游可选项（需扩展）：

  • show_owner：显示仓库所有者。

  • custom_title：自定义标题。

  • hide_border：隐藏边框。

  • disable_animations：禁用动画。

  • 颜色与背景：title_color、text_color、icon_color、border_color、bg_color。

3.4.  github-wakatime（WakaTime 统计卡片）#

  • username（必填）：WakaTime 用户名。

  • theme（可选）：主题名称，默认 default。

  • layout（可选）：布局样式，示例 compact。

  • range（可选）：统计范围（如 last_7_days、last_30_days、last_6_months、last_year、all_time）。

  • api_domain（可选）：自定义 API 域名（如 Hakatime/Wakapi）。

  • custom_title（可选）：自定义标题。

  • hide_title（可选 flag）：隐藏标题。

  • hide_border（可选 flag）：隐藏边框。

注意：仅公开的 WakaTime 资料会显示统计数据；更多细节与演示参见项目主页的 “WakaTime Stats Card” 章节。

4.  注意事项#

  • 这些指令依赖外部服务 https://github-readme-stats.vercel.app/，渲染结果与可选参数由该服务决定。

  • 仅支持上述列出的选项；若需更多定制（如 commits_year、show 等），请参考上游项目并扩展指令的 option_spec。

  • 可用主题（适用于 Stats/Repo/Gist/Top Languages/WakaTime）：default、transparent、shadow_red、shadow_green、shadow_blue、dark、radical、merko、gruvbox、gruvbox_light、tokyonight、onedark、cobalt、synthwave、highcontrast、dracula、prussian、monokai、vue、vue-dark、shades-of-purple、nightowl、buefy、blue-green、algolia、great-gatsby、darcula、bear、solarized-dark、solarized-light、chartreuse-dark、nord、gotham、material-palenight、graywhite、vision-friendly-dark、ayu-mirage、midnight-purple、calm、flag-india、omni、react、jolly、maroongold、yeblu、blueberry、slateorange、kacho_ga、outrun、ocean_dark、city_lights、github_dark、github_dark_dimmed、discord_old_blurple、aura_dark、panda、noctis_minimus、cobalt2、swift、aura、apprentice、moltack、codeSTACKr、rose_pine、catppuccin_latte、catppuccin_mocha、date_night、one_dark_pro、rose、holi、neon、blue_navy、calm_pink、ambient_gradient。

  • Repo 卡片专属：default_repocard。

  • 完整主题列表与预览：Themes README

  • 如需显示私有统计或提升速率限制，请考虑按照上游说明在自己的平台部署该服务并配置令牌。

5.  更多主题示例#

为便于对比，以下示例仅更换 :theme: 选项。

5.1.  Stats 主题示例#

:::{github-stats}
:username: xinetzone
:theme: dark
:show_icons:
:::
GitHub Stats
:::{github-stats}
:username: xinetzone
:theme: tokyonight
:show_icons:
:::
GitHub Stats
:::{github-stats}
:username: xinetzone
:theme: gruvbox
:show_icons:
:::
GitHub Stats
:::{github-stats}
:username: xinetzone
:theme: dracula
:show_icons:
:::
GitHub Stats
:::{github-stats}
:username: xinetzone
:theme: github_dark
:show_icons:
:::
GitHub Stats
:::{github-stats}
:username: xinetzone
:theme: catppuccin_mocha
:show_icons:
:::
GitHub Stats
:::{github-stats}
:username: xinetzone
:theme: nord
:show_icons:
:::
GitHub Stats
:::{github-stats}
:username: xinetzone
:theme: aura_dark
:show_icons:
:::
GitHub Stats

5.2.  Top Languages 主题示例#

```{github-top-langs}
:username: xinetzone
:layout: compact
:theme: radical
:langs_count: 8
```
Top Languages
```{github-top-langs}
:username: xinetzone
:layout: compact
:theme: monokai
:langs_count: 8
```
Top Languages
```{github-top-langs}
:username: xinetzone
:layout: compact
:theme: prussian
:langs_count: 8
```
Top Languages
```{github-top-langs}
:username: xinetzone
:layout: compact
:theme: calm
:langs_count: 8
```
Top Languages

5.3.  Repo 卡片主题示例#

```{github-pinned-repo}
:username: xinetzone
:repo: mystx
:theme: default_repocard
```
Pinned Repo
```{github-pinned-repo}
:username: xinetzone
:repo: tao
:theme: cobalt2
:link: https://xinetzone.github.io/tao
```
Pinned Repo
```{github-pinned-repo}
:username: xinetzone
:repo: mystx
:theme: moltack
```
Pinned Repo

6.  相关链接#

  • 参考项目主页：GitHub Readme Stats

  • Stats 卡片文档：详见项目页面的 “GitHub Stats Card” 章节

  • Top Languages 卡片文档：详见项目页面的 “Top Languages Card” 章节

  • Extra Pins（置顶仓库）文档：详见项目页面的 “GitHub Extra Pins” 章节

  • WakaTime 卡片文档：详见项目页面的 “WakaTime Stats Card” 章节