从 GitHub 导入主题

主题装在哪?

不装在 GitPress.net 的服务器上,也不拷进你的文章仓库。 私有数据仓库里的 gitpress.json 只存一份指针,例如:

"theme": {
  "name": "classic",
  "source": "builtin",
  "ref": "v1",
  "config": { "showAvatar": true }
}

内置主题的 source 是 builtin,实际会去官方公开仓库 tap6/gitpress 的 themes/主题名/,并锁定标签 v1。 导入主题则写成 github:用户名/仓库名#分支或标签。

点「添加到我的主题」之后发生了什么

1. 后台先访问该仓库的 theme.json,确认是 GitPress spec v1、引擎是 Astro。
2. 把仓库地址记到本站的「我的导入」列表(存在 GitPress 控制面,不写入你的文章仓库)。这时还不会换主题、也不会重建。
3. 你在外观页点「启用」后,才把指针写进数据仓库 gitpress.json。
4. 数据仓库的 push 触发 GitHub Actions。
5. Action 在 GitHub 的构建机器上 git clone 那个主题仓库,把你的文章和图片挂进去,执行 astro build。
6. 只有编译好的 HTML/CSS 被推到公开网站仓库,供 GitHub Pages 托管。主题源码不会留在网站仓库里。

表单里三栏怎么填

GitHub 仓库

可以是 owner/repo,也可以直接粘贴浏览器里的仓库地址,包括带 /tree/main/themes/xxx 的页面链接。仓库必须公开,构建机器用匿名 git clone,读不到私有库。

子目录(可选)

如果整个仓库就是一个主题,留空。如果主题在 themes/aurora 这种子文件夹里,填那一段路径。 根目录或该子目录下必须有 theme.json。

分支 / 标签

建议填一个固定标签(如 v1),不要长期钉在会随便 force-push 的分支上。 留空时,若 URL 里没有分支信息,会默认尝试 v1。

导入不会做什么

• 不会把 zip 或主题文件上传到 GitPress.net。
• 不会改你的文章、图片、分类;换主题只改呈现。
• 不会在公开网站仓库里留下一份可编辑的主题源码。下次构建会再 clone 一次当时锁定的版本。
• 作者以后更新了 GitHub 上的主题,你的站点仍用启用时写下的 ref;要升级,需要改列表里的地址或 gitpress.json 里的 ref 后重建。

常见失败原因

• 仓库是私有的,或填错了 owner/repo。
• 指定的分支/标签不存在,或子目录里没有 theme.json。
• theme.json 的 specVersion 不是 1,或 engine 不是 astro。
• 主题能读到,但构建时 Astro 报错(缺依赖、路径不符合挂载约定)。那时请看数据仓库的 Actions 日志。