标题后的 # 锚点:补上缺失的样式,并修跳转定位与无障碍

问题
- 插件 src/plugins/satteri/autolink-headings.mjs 会在每个标题末尾追加
  <a class="anchor"><span class="anchor-icon">#</span></a>,但项目里从来
  没给 .anchor / .anchor-icon 写过任何样式(源码和产物 CSS 都查过,零条规则)
- 结果是那个 # 以纯文本形式常驻显示在每一个标题后面,看起来像 Markdown 语法错误
- 另外标题有 id 却没有 scroll-margin-top,点 # 跳过去标题顶部紧贴视口上沿,
  正好藏在 69px 高的 sticky 导航栏下面

改法
- global.css 补样式:默认 opacity:0 隐藏,鼠标悬停标题(或键盘聚焦锚点)才浮现,
  悬停锚点本身转朱红;触屏没有 hover,直接 display:none(跨标题跳转用目录即可)
- 补 :is(h1..h6)[id] { scroll-margin-top: calc(var(--header-h,69px) + 1.25rem) }
- 插件里给锚点补无障碍名称:aria-label="链接到「标题文字」",图标加 aria-hidden。
  否则读屏会连着念二十几个「#,链接」,完全不知道跳到哪

踩到的坑(已写进操作指南)
Astro 的文章缓存只在 markdown 内容变化时失效,改插件代码不会重新渲染,
必须先 rm -rf node_modules/.astro .astro。第一次改完插件产物没变就是这个原因。

验证:清缓存重建后,产物 HTML 里锚点带上了 aria-label 与 aria-hidden;
产物 CSS 里 .anchor 的 5 条规则 + scroll-margin-top 均正确,
@media(hover:none) 的作用域也确认无误
This commit is contained in:
dsh
2026-09-17 18:37:20 +08:00
parent 93362376f8
commit ef72d52de4
4 changed files with 85 additions and 3 deletions
+13
View File
@@ -299,6 +299,19 @@ sudo sysctl fs.inotify.max_user_watches=524288
如果连空态提示都看不到,检查 `src/data/reading.json` 是否存在(这个文件要提交进 git)。
**改了 markdown 插件却不生效**
Astro 会把渲染好的文章缓存到 `node_modules/.astro`,而这个缓存**只按 markdown
文件内容算 key,不看插件代码**。所以改完 `src/plugins/satteri/*.mjs` 之后,
已经渲染过的文章不会重新跑插件 —— 你会以为改动没生效,其实是吃了缓存。
```bash
rm -rf node_modules/.astro .astro && pnpm build
```
(这个坑是给标题锚点补 `aria-label` 时踩到的:插件明明改了,
产物里的 HTML 却还是老样子。)
**`pnpm dev` 启动时满屏刷红**
历史上踩过两个独立的原因,都已修好,这里记下来免得再犯: