Github美化过程记录

最后的效果可以参考我的Github主页：

wenjiew-astro (Wenjie Wang)

有很多很好的教程分享了自己的美化之路，我是个懒狗，所以就直接 Copy & Paste，然后 改改改 就成了我自己的主页了，下面是我参考的最主要的教程来源：

(99+ 封私信 / 80 条消息) Github 首页美化教程（一）：打造个性化的GitHub首页 - 知乎

当然了，还有很多很好的教程。如

超详细的 GitHub 个人主页美化教程 - peterjxl - 博客园

我这里就主要记录我自己的修改过程。

Tips

你可以直接复制我的仓库，然后按照我的方法，就可以很容易构建你自己的主页了！

Have a nice day !!

1.首先要找到一个我们喜欢的主页

因为我们不是自己做主页，所以第一要务就是要找到一个我们心仪的主页，然后”参考“一下（你懂我的意思吧）。这里我的来源是孙同学的主页 sun0225SUN (Guoqi Sun)。

找到之后，其实我们有两种方式，第一种就是直接克隆他的仓库，因为这个主页要求仓库的名字和用户的名字相同才会显示，所以在克隆的时候我们把仓库的名字改成我们自己的用户名就可以了。还有一种，就是把这个仓库下载下来，然后我们自己新建一个与用户名同名的仓库，使用电脑的git或者Github Desktop软件把这个代码推到我们刚刚建立的仓库里面去。

注意要先打开仓库权限

  • 仓库 Settings → Actions → General → Workflow permissions
  • 选 Read and write permissions
  • 如果看到 “Allow GitHub Actions to create and approve pull requests”，也勾上

这里我推荐第二种，但其实第一种也没有任何问题。

之后我们只需要去改 README.md 这个文件内容就可以了，文件里面写了很多的注释，我相信你很容易就能看懂，下面我主要写一些我自己配置过程中的问题。

配置过程中我遇到的问题 — token问题

这个问题是最头疼的问题了，修改过程中最麻烦的就是每一个插件都需要一个权限，这个权限主要是用来给自己建的那些action让它去自动更新我们的这个 README.md 文件。因此下面我就把所有需要用到的权限一次性列出来：

WakaTime Token

这个主要作用是用来记录我们的编程时间的，官网是 Dashboard - WakaTime 。

我们需要在官网注册一个账户，然后在设置里面找到 Edit profile ，在这里面该我们的名字和用户名。

注意，这里的用户名就是你真正需要写到 README.md 中的名字

之后，在设置里面你会看到 account 里面有 Secret API Key ，这个记住他，我们有两个地方需要用到：

仓库

  1. 先拿到你的 WAKATIME_API_KEY

    • 登录 WakaTime

    • 右上角头像 → Settings → API Key

    • 会看到一串很长的 key（类似 1234abcd-xxxx-xxxx-xxxx-abcdef123456）

    • 复制下来备用

  2. 在 GitHub 仓库里添加 Secrets

    • 打开你的仓库 → 点上方菜单里的 Settings

    • 左边栏找到 Secrets and variables → Actions

    • 点 New repository secret

    • Name 填：WAKATIME_API_KEY

    • Value 填：刚才复制的那串 key

    • 保存

你的代码编辑器

  • 在你的编辑器（VS Code、PyCharm 等）里安装 WakaTime 插件。
  • 输入你的 API Key（在 WakaTime Settings → API Key）。
  • 正常写点代码，至少运行几个小时，产生实际的编码时间数据。
  • 等一天（WakaTime 的 public profile 只显示“过去的天数”，新账号当天是不会展示的）。

各种Action的Token

.github/workflows 里面总共有六个Action：

  1. blog.yml
  2. contrib.yml
  3. fork_star.yml
  4. metrics.yml
  5. snake.yml
  6. waka.yml

每一个Action他们需要的Token都不一样。虽然我们可以定义同一个api_key，但是Token的名字却不尽相同。（这里也就是我为什么推荐你用第一种方式，因为如果用第二种的话，可能还需要改更多的内容）

下面我写一下需要做的事情：

生成 PAT

  • 去 GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
  • 点击「Generate new token (classic)」
  • 勾选最少的权限：
    • repo
    • read:user
    • read:org（如果你要展示组织/私有仓库信息）
    • workflow
  • 复制生成的 token（格式是 ghp_XXXXXXXXX...）

添加到仓库 Secrets

  • 打开你的仓库 wenjiew-astro/wenjiew-astro
  • Settings → Secrets and variables → Actions → New repository secret
  • Name 填：GH_TOKEN
  • Value 填：刚才生成的 PAT

你需要把这个PAT放到如下几个不同的名字中去：

  1. GH_TOKEN
  2. ACCESS_TOKEN
  3. METRICS_TOKEN

你可能会有疑问，为什么要新建这么多Token，只用一个不行吗？答案是，可以！But，如果你这里只建一个Token的话，那你就需要去改那好几个yml文件，如果你想改的话当然没问题，你可以去改。

还有一个小点

你会在 README.md 文件最后看到这样一句话：

<img width="120%" src="https://repobeats.axiom.co/api/embed/7aa7311e6885fc4b499b17d5c47c0cd5cbca9d4d.svg" />

这一行是 Repobeats 服务，自动生成一张仓库贡献的动态分析图。比如提交数、活跃度、PR、issue 等，会显示成五颜六色的曲线图。这个 Repobeats 图，它并不是记录你的「整个 GitHub 账号」，而是记录某一个具体仓库的活动情况。

你只需要在 Repobeats 这个网页中登录你的 Github 账号，然后选择需要记录的仓库，就会有一句这样的话：

// Add the following to your README.md to embed Repobeats

![Alt](https://repobeats.axiom.co/api/embed/7aa7311e6885fc4b499b17d5c47c0cd5cbca9d4d.svg "Repobeats analytics image")

你只需要把这里面的网址 替换掉就行了。这个时候基本就大功告成了。

如果你还有一个博客，那你就需要配置一下 blog.yml 这个文件。

我的博客是 Wenjie Wang，是部署在 Github 上面的，下面是 GPT 给我写的教程，但是我现在没有那个电脑，之后尝试了再更新。

+++

明白～Hexo 默认不自带 RSS，需要先装插件来“产出”一个 feed，然后再用那个 GitHub Action 把文章列表写进 README。

下面按顺序来：

1) 给 Hexo 生成 RSS（一次性设置）

在你的 Hexo 博客目录（有 source/、themes/ 的那个根目录）里执行：

npm install hexo-generator-feed --save

然后在 站点配置文件 _config.yml（根目录的，不是主题里的）加入/修改如下：

# 站点基本信息（确保正确，影响 feed 的链接）
url: https://wenjiew-astro.github.io
root: /
permalink: :year/:month/:day/:title/

# RSS 配置（hexo-generator-feed）
feed:
  type: atom            # 可选 atom | rss2 | both
  path: atom.xml        # 生成文件名（常见：atom.xml 或 rss2.xml）
  limit: 10             # 列出最近 N 篇
  hub:
  content: true         # 是否包含全文（true/false）

生成并预览看看是否有 atom.xml：

hexo clean
hexo g
hexo s

打开浏览器访问本地 http://localhost:4000/atom.xml 能看到 XML 就说明成功了。

部署后，你的线上地址就会是（按上面配置）：

https://wenjiew-astro.github.io/atom.xml

如果你的站点是 项目页（repo 不是 wenjiew-astro.github.io 而是别的），那线上路径会是：
https://wenjiew-astro.github.io/<repo-name>/atom.xml。
你的是用户页（域名就是用户名.github.io），所以直接 /atom.xml。

2) 改 GitHub Actions（把 RSS 地址换成你的）

把你现有的 workflow 改成这样（只改 url 即可；其余保留）：

name: Recent Blog

on:
  schedule:
    - cron: "0 0 * * *"   # 每天 00:00 UTC 跑一次
  workflow_dispatch:

jobs:
  build:
    runs-on: ubuntu-latest
    name: generate-readme-feed
    steps:
      - uses: actions/checkout@v4
      - uses: sarisia/actions-readme-feed@v1
        with:
          url: "https://wenjiew-astro.github.io/atom.xml"  # ← 用你刚生成的 feed
          file: "README.md"
          # 可选：最多显示 5 篇、每项的格式
          max_item: 5
          format: "- <a href='${link}'>${title}</a> <sub>(${pubDate})</sub>"
      - uses: sarisia/actions-commit@master

3) 在 README 放占位符

在 README.md 里加：

## 📝 最近更新
<!--START_SECTION:feed-->
<!--END_SECTION:feed-->

Action 每次跑，会自动把最新文章列表填充在这两行之间。

常见问题排查

  • 访问 404：确认最终线上地址是否是 /atom.xml（或你设置的 path）。用户页是根目录；项目页要带仓库名。
  • feed.xml / rss.xml 打不开：你没有装插件或 feed: 节没配置；检查 _config.yml 是否在站点根而不是主题配置里。
  • 时区/时间：Hexo 默认 UTC，想显示北京时间可以在 README 的格式里自己处理，或保持简单用 ${pubDate}。
  • 缓存：GitHub 对 README 图片/内容有缓存，第一次更新后稍等一会儿或点进 Actions 的运行日志确认是否写入成功。

如果你把 _config.yml（相关几行）贴我，我可以帮你确认最终线上 feed 的准确 URL，并把 workflow 的 format 再美化一下（比如只显示日期不含时区、加 Emoji 等）。