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

🗺 博客地图 ｜ 全部系列的总入口（本篇只管 G 进阶篇）

这是 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 事件，编辑即自动重建），所以这张表会一直是最新的。

另一条线：地基篇（B 系列）

G 系列默认读者已经有一个博客。不少新读者反馈"连仓库都还没建，不知道该从哪篇看起"，于是另开了一条零起点线，从"一个 GitHub 账号都没有"讲起：

👉 从零开始请直接读 B00 地基篇总览，B01–B03 已发布、B04–B08 计划中；地基篇的路线图表与发布日志都维护在 B00 一篇里，本文不再搬运，以免两张表各说各话。

两条线的分工一句话：B 系列让你拥有一个博客，G 系列让你拥有"你的"博客。

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

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

2026-09-15 上游复盘：为什么说"功能做得差不多了"

当天又把官方仓库和社区翻了一遍，给"还该不该继续堆功能"一个明确交代：

• 官方没有新轮子：插件仍是 6 个（GmeekBSZ / GmeekTOC / GmeekTocBot / GmeekVercount / articletoc / lightbox），最后更新停在 2026-02-05；插件基地 #167 两年来无新评论。唯一没装的 GmeekBSZ 明确不装——Vercount 已覆盖其功能，且它在 Safari 下有 PV 重复统计的 bug。
• 搜索只搜标题，知道但暂不修：框架 tag.html 的 searchShow() 只对列表条目标题做 indexOf 过滤，不索引正文。全站 25 篇标题均可命中；正文搜索要引入 lunr/Pagefind 一类索引，和静态极简路线冲突，等文章量级真的需要再说。
• 图片懒加载，收益以毫秒计：框架正文 img 无 loading="lazy"，但全站图片总量极少（本批补图后才略有改善），不做。
• 分享按钮 / 友链页 / 独立域名 + 百度：均为主动放弃而非欠债——系统自带分享面板与 URL 复制已够用；友链等有真实社交圈再开；百度对未备案的 github.io 域名收录极差，G04 已决定跳过。

结论：除 G17 四项 SEO 技术缺口外，没有"该做没做"的功能了。下一步的写作方向从"造功能"转向"晒方法论"——截图教程、收录实战、跟版记录都属此类。

2026-09-16 上游回馈第二波：三 PR + 一 issue + 两条评论

G17 之后把 11 个自研件整体过了一遍筛子（详见 番外二），结论落地为：

• 三个 PR 全部 Open 待合并：#319（无标签 issue 增量构建 KeyError，3 行）、#320（GmeekExternal 外链新标签，42 行，对接 #186）、#321（GmeekSEO 四件套，138 行，对接 #145 维护者 2024 年的承诺）；
• 根治 issue #322：Gmeek.py:347 直接取 issue.body 原文做 description，建议构建期从渲染后 HTML 转纯文本——插件是过渡，构建期才是根治；
• review #307（sitemap 内建生成）：五条核对确认（分页页数边界、labelColorDict 时序、runOne 数据完整、两种 Pages 形态、输出位）+ 两条非阻塞建议；质量过关，合并后本站 sitemap_gen.py 回迁内建方案；
• #318 伪 bug 排查：当天构建日志实证 lxml 6.1.3 有 cp38 manylinux wheel，帮助定位为环境问题；
• 第二梯队压着不提：PrevNext/ReadTime/Pager/Archive 四个等维护者对前三连的响应节奏，不一次性轰炸；Mermaid（3.5MB 本地资产）与 articletoc（类名兼容包袱、原作者 PR 在排队）确认缓提。
• PR 前的通用性加固已同步本站：GmeekSEO.js 兼容 project pages 子路径、未配 ogImage 时省略图片字段（commit 9e9f21e，已重建上线）。

2026-09-17 站外多平台分发调研（备忘，暂不执行）

番外四发布后盘点了"把系列教程分发到知乎/CSDN 等平台"的可行性，结论先存档，近期不做，有传播需要时再启动。

平台 API 现状：

两个所有平台通用的坑： ① 知乎/CSDN/博客园都不渲染 Mermaid，必须先用本地 mermaid.min.js + CDP 渲染成 PNG 再上传；② 图片外链——知乎粘贴 Markdown 会自动转存，CSDN 有防盗链需重新上传。

定位澄清（为什么做、不为什么做）： 分发不是为了给独立站引流——平台外链是 nofollow/中转链接不传权重，百度基本不收录 github.io，独立站也没有订阅/产品等转化路径。真正的价值是：搜索占位（百度"Gmeek 教程"关键词目前是空坑）、防搬运抢原创、给上游 Gmeek 项目带新用户、跨平台账号资产。

同日排查上游官方入口的结论： Gmeek 仓库 README 无教程区、Discussions 未启用、无 docs/awesome 仓库、作者博客只有自家【Gmeek进阶】系列；作者在 #179 明确"没有交流群，issue 讨论即可"，无运营社区聚合的打算。唯一社区入口是 hst1189 发起的#285 网站收录虫洞（gmeek.dpdns.org 随机跳转，收录网站而非教程，作者点过赞但非官方背书，今年仍活跃）。未来两个动作挂起：虫洞跟帖报名（一分钟）；等三个 PR 有合并进展后再开"系列教程自荐 issue"（届时身份是贡献者而非广告）。番外五既已发布（2026-09-18），择机可去 #311 Gmeek 发帖 Skill 分享"图片静态文件走 git commit"的解法（该帖唯一评论正卡在这个问题上）。

若未来启动，三步走： ① 先写本地"多平台适配包"导出脚本（gh issue view 取 Markdown 源 → Mermaid 转 PNG → Alert 语法降级 → 输出 dist/<n>/文章.md + images/），纯本地零风险；② 博客园/Dev.to 走 API 自动化；③ 知乎/CSDN 半自动——脚本备好包，人工登录粘贴发布，文末仅留一行原文链接满足原创声明，正文操作链接指向上游仓库而非自己的站。

2026-09-18 番外五发布：踩坑经验的四层归宿

发布 番外五·踩坑手册怎样变成 AI 技能，兑现番外四结尾的预告。全篇以"mermaid v11 时序图信号文字在亮色文章页不可读"这一个坑为贯穿案例，讲清一条经验的四层归宿——博客写给人看、CLAUDE.md 每次会话全量在场立规矩、Auto memory 跨会话记事实（MEMORY.md 索引常驻、主题文件按需读）、Skill 只有 description 常驻而正文/脚本调用时才加载（渐进式披露）。所有机制以官方文档 code.claude.com/docs/en/memory 与 /skills 为凭，关键结论：CLAUDE.md 与 memory 都是上下文而非强制配置（硬拦截要 PreToolUse hook）；多步流程应从记忆/规矩升级成 Skill。

同一坑的四份归宿都已落地：① 博客——B01/B04 时序图已改 flowchart、本篇讲清原理；② CLAUDE.md——全局那份 Mermaid 约定里"时序图可追加 actorBkg 等变量"的条款已被 v11 证伪，2026-09-18 经本人确认已改为"示意图一律优先 flowchart TD、慎用 sequenceDiagram；确需时序图信号文字需自备不透明底盒"（配图 extra5-claudemd.png 为修订前实拍，留作 before 示意）；③ memory——教程规划已记 v11 教训；④ Skill——SKILL.md 新增"重型运行时别赌固定 settle、改图先本地 file:// 预检、flowchart 优先"两段纪律。配图 8 张：1 张当晚 A/B 实测对比、1 张文内原生 flowchart、4 张纯本地 conhost（CLAUDE.md / memory 目录与索引 / SKILL.md frontmatter / 技能目录含 ui-shot.ps1 SAFETY 头）、2 张官方文档暗色实拍；全程零借窗。拍摄新增一条工具经验：Windows Terminal 会劫持 Start-Process powershell 的新窗成标签页，显式 conhost.exe powershell.exe … 才起独立经典控制台；Win11 经典控制台抓图要用 DWM 扩展框（DwmGetWindowAttribute attr 9）取物理几何，比 GetWindowRect 大约 1 倍 DPI 边框量。

参考资料汇总

• 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 清单清零）均已完成；方法论番外已有五篇：番外·给博客拍证件照（零依赖 CDP 无头截图，成品脚本 tools/cdp-shot.js）、番外二·开源回馈流水线（三个上游 PR 待合并，见上方 2026-09-16 小节）、番外三·gdigrab 抓窗口（浏览器外截图，成品脚本 tools/shot-window.ps1）、番外四·点到为止（借用户已登录浏览器窗口拍登录态页面，Win32 UI 自动化 + 安全边界，成品脚本 tools/ui-shot.ps1；截图三部曲——浏览器内 CDP／浏览器外 gdigrab／登录态借窗——至此收束）与 番外五·踩坑手册怎样变成 AI 技能（博客/CLAUDE.md/memory/Skill 四层归宿，见上方 2026-09-18 小节）。2026-09-16 另发布 G18 被浮动挤扁的"上一篇/下一篇"：G08 导航卡片在移动端被版权小字的 float:right + BFC 避让规则压成 60% 窄列、标题竖排；clear:both 拿回全宽、小屏去浮动、meta 行合并，移动/桌面同取景前后对比验收。零起点读者另走地基篇（B 系列）：B00 地基篇总览以及 B01 18 秒建站实录、B02 毛坯房装修：认识 config.json、B03 在 Issues 里过日子、B04 门铃与名片：评论区与 About 页 均已发布；地基篇的路线图表与发布日志统一维护在 B00 一篇里（本文不再搬运），下一篇动手向为 B05 Actions 篇（回收 B04"评论数为何不实时"的伏笔）。G 系列方向下一篇待写仍是约 2026-09-21 的 G04 收录实战番外——用 Google/Bing 的真实收录数据回答"RSS 当 sitemap 提交到底有没有用"，届时一并验收 G17 富结果与清洁摘要的真实生效情况、追踪上游 PR 进展。更远的候选见上方选题池。