Gmeek 插件与功能全景调研：系列教程总揽（第 0 篇）

这是 Gmeek 系列教程的第 0 篇：一张完整的功能地图。本文不教具体操作，而是回答两个问题——Gmeek 到底还藏着哪些能力？哪些值得搬、哪些不值得搬？文中每个结论都附了一手出处（官方源码、作者博客、社区 issue、原始教程），后续每动手复现一个功能，就会发一篇编号教程并在文末路线图里打勾。博客现阶段的内容方向也由此确定：先把 Gmeek 本身玩透。

怎么读这篇文章

• 想抄作业：直接跳到文末「系列教程路线图」，按编号等后续教程；
• 想自己深挖：每个功能都附了出处链接，优先看源码而不是二手转述；
• 想看结论：每节末尾都有"叶扬的判断"。

本系列的编号约定：第 0 篇是总揽，之后每篇教程以 G01、G02…… 编号，文末路线图会持续更新。前面三篇相关文章是本系列的前传：

• 用 GitHub Issues 写博客：Gmeek 搭建全过程与原理
• Gmeek 右侧"文章目录"导航栏：插件原理与接入全过程
• 一个博客除了评论还需要什么：叶扬的博客基础功能建设清单

调查的一手来源

结论不是凭印象，全部来自以下材料交叉验证：

一、官方插件全档案

官方插件一共 5 个，全部位于源码仓库 plugins/ 目录，机制完全一致：一个自包含 JS，放进 static/ 目录，用配置字段注入页面，CSS 自己动态注入。这是 Gmeek 插件哲学的核心——不改上游模板，升级零冲突，删掉一行配置即回退。

1. GmeekVercount.js —— 访问统计（已装）

• 功能：站点总 PV/UV、文章页 PV，数据自存在 Vercount 服务，无需注册。
• 出处：插件源码
• 官方态度：进阶教程里首推。替代的不蒜子（busuanzi）已长期无人维护，且在 Safari 下计数不准。
• 叶扬的判断：保留。只记数字、不追踪个人身份，符合第 4 篇立的统计克制原则。另一个统计插件 GmeekBSZ.js（不蒜子）不要装。

2. GmeekTOC.js —— 右侧文章目录（已装 已退役留档，见 G16）

• 功能：扫描正文 h1~h6 生成固定在右侧的目录，按标题级别缩进，窄屏自动收为文章内块，附 Top 回顶按钮。零依赖，100 行。
• 出处：插件源码；接入全过程见本站第 3 篇教程。
• 关键坑：只能走 script 字段（仅文章页注入），不能放 allHead——首页没有 id="content" 元素，会抛 TypeError。
• 叶扬的判断：官方文档站自己在用，配色全走 Primer CSS 变量自动适配暗色。本站第一个接入的插件（前传 #3），平铺目录无 scrollspy；G16 起被本地化改造的 GmeekTocBot 接替，config 摘除引用、文件留在 static/plugins/ 留档可回退。

3. lightbox.js —— 图片灯箱（✅ 已装，见 G05）

• 功能：文章图片点击放大，支持滚轮缩放、左右键切换上一张/下一张、触屏滑动、相邻图片预加载、毛玻璃遮罩、点遮罩关闭。
• 出处：插件源码（357 行，零外部依赖，所有样式与 DOM 都由插件自建）；官方进阶教程收录，由社区用户 Tiengming 贡献。
• 叶扬的判断：官方插件里完成度最高的一个，G05 已接入（static/plugins/lightbox.js + config script 拼接）；教程里用 og.png/favicon.svg 两张图做了可点击演示。

4. articletoc.js —— 悬浮按钮式目录（✅ 已装，见 G14）

• 功能：不在正文里占位置，而是在右下角放一个 ☰ 圆形按钮，点击弹出目录浮层，再点外部关闭；自带亮/暗两套 CSS 变量。
• 出处：插件源码，同为 Tiengming 贡献。
• 叶扬的判断：原版与 GmeekTOC 同名 .toc，同时加载会被浮层的 opacity:0;visibility:hidden 连坐藏掉桌面目录，所以官方只让二选一。G14 已用类名隔离（.toc-mobile）实现共存：桌面 >1249px 常驻右侧目录、圆形按钮隐藏；≤1249px 隐藏桌面目录退化出的文首静态块、右下角 ☰ 浮层当班（G16 起桌面目录换成 GmeekTocBot，契约不变、分工不变）。另把原版 prefers-color-scheme 暗色换成 Primer 变量（#196 三态失配），补空标题守卫、点链接/Esc 收起与 aria-expanded 键盘可达。

5. GmeekTocBot.js —— tocbot 版目录（✅ 已本地化接入，见 G16）

• 功能：封装成熟库 tocbot，视觉层级更好，独有滚动时高亮当前章节能力。
• 出处：插件源码；依赖 cdnjs.cloudflare.com 上的 tocbot 4.27.4。
• 叶扬的判断：功能最强但原版依赖第三方 CDN，与本站"静态资源全部本地化"的原则冲突。G16 已按当年预案落地：tocbot 4.27.4 引擎（11KB）下载到 static/tocbot/tocbot.min.js，CSS 六条规则内联并全换 Primer 变量；适配版 static/plugins/GmeekTocBot.js 另修官方壳六处将就（id 缺 toLowerCase、100vh 空白 div、容器清空、window.onscroll 覆盖、无空标题守卫、暗色裸奔），接替 GmeekTOC 接管桌面目录。

插件组合用法（官方进阶教程原文给出的方式）：多个插件可以直接拼在同一个字段里：
"script":"<script src='...GmeekTOC.js'></script><script src='...lightbox.js'></script>"

二、改一行配置就能解锁的框架能力

读 Gmeek.py 第 91 行的默认配置字典和作者本人博客的 config.json，发现一大批框架早就支持、但本站配置里没写的能力。这是性价比最高的一层：不用写任何代码。

固定页面与导航

这正是第 4 篇路线图里 P0「About 页面」的官方正解，已由 G01 完成（含一个真实踩坑：新增 singlePage 后必须手动全局重建）。

页脚信息

bottomText 一举解决路线图里的「文末版权声明」，已由 G02 完成（另含 startSite 运行天数与日期格式的时区坑）。

身份与分享

favicon + ogImage 已由 G03 完成：自制"叶"字 SVG 图标（明暗自适应）+ Pillow 生成 1200×630 PNG 封面；注意 ogImage 只认位图绝对 URL，SVG 不行。

注入与自定义（插件体系的另一半）

出处：模板 base.html、post.html、plist.html 中的注入点，以及 Gmeek.py:91 默认值。

外观与排版

URL 与订阅

三、单篇文章的"隐藏语法"

Gmeek.py:355 会解析每篇 issue 正文最后一行的特殊 HTML 注释，实现文章级配置，这是官方进阶教程里明确支持、但很多人不知道的功能：

<!-- ##{"script":"<script src='...'></script>","style":"...","ogImage":"https://.../cover.png","timestamp":1700000000}## -->

G06 已完成（教程）：文章自身就是活 demo——末行 JSON 给本篇注入了 h2 绿竖条、文末虚线徽章和控制台彩蛋。补充两个实测细节：解析行在新版源码为 Gmeek.py:357；gh API 发布的 LF 正文会被 GitHub 规范化为 CRLF（backup 实锤），所以换行坑只存在于本地调试。

四、你可能没意识到的开箱功能

以下能力不用配置、不用插件，写 Markdown 时直接存在：

1. 代码块一键复制：GitHub 同款 copy/check 图标按钮，post.html 内置（对应早期社区 issue #134 的诉求，现已官方解决）。
2. 数学公式按需加载：正文直接写 $E=mc^2$（行内）或 $$...$$（块级），GitHub 渲染成 <math-renderer> 标签后，框架剥掉标签壳、注入 MathJax 3（jsdelivr CDN），不写公式的文章零开销（G07 已实测；坑：正文中的美元金额要用反引号包，避免成对 $ 被当公式）。
3. GitHub Alert 提示块：> [!NOTE]、> [!TIP]、> [!IMPORT]、> [!WARNING]、> [!CAUTION] 自动渲染成 GitHub 官网同款彩色边框块，框架检测到 markdown-alert-title 自动补五套配色（Gmeek.py:159 起，颜色走 Primer CSS 变量，明暗自适应）。注意 API 渲染的标题是英文 Note/Tip/…，静态页不做本地化。
4. 三态主题与评论联动：亮 → 暗 → 跟随系统循环；切换时通过 postMessage 让 utterances 评论 iframe 同步换肤（base.html:54）。
5. 列表分页：文章数超过 onePageListNum，首页自动出现上一页/下一页。
6. 每日定时重建：工作流除了监听 issue 事件，还有一条 schedule: cron("0 16 * * *")，即北京时间每天 0:00 自动全量重建一次。Webhook 丢失、改了配置忘记手动构建，第二天都会自愈。注意：Issue 事件只触发增量构建，config.json 的结构性变更（如新增 singlePage）不会被加载，必须手动跑一次全局重建——G01 实操时踩过这个坑。
7. Markdown 原文自动备份：每次构建把 issue 正文存进仓库 backup/ 目录，git clone 即整站离线副本。
8. RSS 即 sitemap：见下节，单独说。

写作技巧已由 G07 完成：Alert/公式零配置；Mermaid 非内置（GitHub API 只语法高亮不出图）。G15 已把 mermaid 升级为自动检测、按需加载：static/plugins/GmeekMermaid.js 检测到 highlight-source-mermaid 块才动态加载 static/mermaid.min.js（v11，3.5MB），跟随三态主题重绘，作者零配置——G07 时代「含图文章末行手写挂载 JSON」的旧三件套已退役（末行 JSON 漏写即静默失败，是 G15 案发根因）。另有内联反引号 直出 HTML 的彩蛋（围栏代码块不生效）。

五、SEO：被问得最多，答案却最简单

社区 issue #145 里有人建议生成 sitemap.xml，作者的回复是：rss.xml 已包含全站所有重要页面链接，他自己就是把 rss.xml 提交给 Google 的；提问者随后验证，必应和谷歌都能正常识别 RSS 作为站点地图。

G04 已落地（教程）：

• Google Search Console / Bing 站长工具直接提交 rss.xml 即可（Bing 添加站点时还能从 GSC 一键导入，验证状态继承）；
• 百度的 sitemap 工具按 sitemaps.org 协议解析、不认 RSS，已在工作流新增 sitemap_gen.py，每次构建从 postList.json 自动生成标准 sitemap.xml，三家都提交它做双保险；
• RSS 之外，robots.txt 和自定义 404.html 直接放进 static/ 根目录即可，构建时原样复制到站点根，GitHub Pages 原生识别（✅ 已完成，见 G11：robots 显式 Allow + Sitemap 绝对 URL；404 独立页 noindex、三态主题读 meek_theme、fetch 最新 5 篇）。

六、社区生态盘点：有宝贝，也有大坑

Gmeek 没有独立插件市场，issue #167「插件分享基地」事实上承担了这个角色。翻遍社区代码后：

值得借鉴的：

• 数字分页条 ✅：把"上一页/下一页"换成 1/2/3 页码，文章几十篇以后有用，issue #186 需求 2。社区李轶凡《给博客添加数字分页条》提供了思路，但 2026-09 调研时原站 DNS 失联、GitHub 仓库源码已撤、Wayback 无存档，已完成见 G13（借鉴失败转为自研）：static/plugins/GmeekPager.js，90 行零 CSS——复用 Primer 21 内建 .current/.gap 样式与三档响应式显隐；保留框架原生 prev/next 节点只插中间数字；config.indexScript 首次启用（仅注入 index/pageN，tag 页不注入）；fetch postList.json 计数过滤 labelColorDict；≤7 页全显、否则首尾页+当前页±1+省略号；单页/失败/超界三态静默降级。
• 外链新窗口打开 ✅：同 issue #186 的头号需求，已完成见 G12。static/plugins/GmeekExternal.js：URL 构造器按 hostname 判内外（协议相对 URL/自家绝对 URL 都不误判），外链补 target=_blank + 合并 rel=noopener；显式 target 不覆盖、rel 只合并不替换；不自动加 nofollow（SEO）、不加 noreferrer（保留来路）。

看看就好、不要搬的：

• 社区用户 luliy6 的 enhance.js：约 5884 行的整站换肤方案——开屏动画、全屏 Hero、六张分类卡片、APlayer 音乐播放器、抽屉式菜单。代码本身值得学习"一个 JS 能做到什么程度"，但它与本系列第 4 篇立的三条规矩（静态优先、走插件机制不改模板、为长期写作服务）全部冲突，明确不借鉴。
• GitHub 代码搜索能找到的其他"插件"，90% 是把官方 5 个 JS 复制改名，无新东西。

七、框架的空白：需要自研的功能

对照第 4 篇的清单，以下功能官方与社区都没有可靠现成方案，需要自己写插件。好在 Gmeek 把数据都放在了 postList.json，自研难度不高，这也会是本系列最"硬核"的几篇：

这三篇完整演示"如何写一个自己的 Gmeek 插件"，而不只是抄配置。

八、系列教程路线图

总揽即 roadmap。每完成一篇，这里会更新链接；状态图例：✅ 已发布 / ⏳ 计划中 / 💤 远期再说。

更新方式：每篇教程发布后，叶扬会回来编辑本文（Gmeek 监听 issue 的 edited 事件，编辑即自动重建），所以这张表会一直是最新的。

收官之后：候选选题池（G17 起）

正篇 G01–G16 收官，建设清单（前传 #4）也已回填，但清单并非一无所有。2026-09-15 盘出以下候选，按写作意愿排序：

参考资料汇总

• Gmeek 源码：https://github.com/Meekdai/Gmeek
• 官方进阶插件教程：https://blog.meekdai.com/post/%E3%80%90Gmeek-jin-jie-%E3%80%91-cha-jian-gong-neng-de-shi-yong.html
• 官方快速上手：https://blog.meekdai.com/post/Gmeek-kuai-su-shang-shou.html
• Primer CSS（GitHub 同源设计系统）：https://primer.style/css
• utterances 评论系统：https://utteranc.es/
• tocbot 目录库：https://tscanlin.github.io/tocbot/
• Vercount 计数服务：https://vercount.one/
• 插件分享基地（issue #167）：Meekdai/Gmeek#167

小结

调研结论可以浓缩成三句话：

1. 配置层的红利还没吃完——About 页、版权声明、运行天数、favicon、分享封面全是一行配置的事，这是接下来 G01–G03 的内容；
2. SEO 几乎零成本——RSS 直接当 sitemap 提交，robots/404 放静态目录即可；
3. 真正有含金量的是自研三小件（上下篇、阅读时长、归档页），它们会逼出"如何写一个 Gmeek 插件"的完整方法论，那才是这个系列从"会用"走向"会造"的分水岭。

G01–G16 已全部完成，路线图正篇收官。接下来首选 G17 SEO 收尾战（canonical + JSON-LD + twitter:card + 清洁 description，把前传 #4 清单上仅剩的技术缺口清零）；其后约 2026-09-21 是已承诺的 G04 收录实战番外——用 Google/Bing 的真实收录数据回答"RSS 当 sitemap 提交到底有没有用"。更远的候选见上方选题池。