Guoguo
1e109fdc1b
ci(links): check notebook markdown cells and video/audio sources
...
The image link check only looked at markdown and <img> tags, so two kinds
of references were never verified:
- MaixPy3 docs are Jupyter notebooks (.ipynb). The GIF->WebP conversion
updated the markdown pages but not the notebooks, and the check did not
notice.
- <video>/<source>/<audio> src and poster attributes.
Both kinds of breakage stay invisible on the live site because the COS
bucket still serves files that were removed from the repo.
Notebooks that are not valid JSON are reported on stderr instead of being
skipped silently. Also drop the two baseline entries fixed by #1048 .
2026-10-13 16:18:34 +08:00
zepan
b127ebeb82
fix(docs): apply human decisions on the remaining broken image links
...
人工逐条确认后处置 39 项：
- delete 33 处：素材在整个仓库都不存在（从未提交或连同目录被删），
删掉整个图片标记而非只删路径，markdown ![]() 与 <img src> 两种
写法都处理；表格内只清空单元格、保留表格结构；删后遗留的空
<center class=half></center> 等空壳标记一并清理
- use 1 处：uboot_conf_9.gif -> uboot_conf_9.jpg（扩展名写错）
- todo 4 处：保留引用等工程师补图，见下
- skip 1 处：pages/index/zh/threshold.html 的 demo_color.jpg
读写文件保留原始行尾——这批文件多为 CRLF，用默认模式会把整个文件
转成 LF，改动量会从 42 行虚增到 1200 多行。
待补素材（3 张，补进来后基线可再缩减）：
docs/hardware/assets/NanoKVM/guide/atx_2024.png
docs/hardware/assets/NanoKVM/pro/ledstrip/ledstrip_show.png
docs/hardware/en/logic_analyzer/slogic16u3/assets/Screenshots/SLogic_Connect_1.png
断链 39 -> 5。
2026-10-07 21:24:11 +08:00
zepan
5ad7a1a59e
fix(docs): resolve cross-tree and case-only ambiguities; ignore commented-out refs
...
- Lichee-RV 文档在 docs/soft/Lichee/zh/，素材却在 docs/hardware/zh/lichee/
assets/RV/，中英各存一份。按页面语言消歧（两份 md5 相同），2 处
- BiT.png / Bit.png 仅大小写不同、内容相同，取与引用大小写一致的那份。
注意它写在 <img src> 里而非 markdown ![]()，替换要覆盖两种写法
- 检查器补剥离 HTML 注释：被 <!-- --> 包住的引用根本不渲染，
算断链是误报（sipeed_longan_logo.jpg 即此例）
断链 50 -> 39。剩下 37 处是文件在整个仓库都不存在，自动规则已无能为力。
2026-10-07 21:14:31 +08:00
zepan
14df4354c3
fix(docs): repair misspelled image filenames
...
目录没问题，是文件名本身拼错了：
enviroument.png -> environment.png （作者把自己文章名都拼错了）
succeed_login.png -> susseed_login.png （这次反过来，是文件名拼错，
引用是对的）
判定：引用指向的目录必须存在，在该目录内按编辑距离找同扩展名的近似
文件名，且最优解必须严格优于次优解。
护栏：纯数字或短于 4 字符的文件名不参与近似匹配——实测有一例
1.jpg 被匹配到 WE1.jpg，编辑距离在短名上毫无区分力。
断链 52 -> 50。
2026-10-07 21:09:50 +08:00
zepan
8a1ee30543
fix(docs): repair references to renamed asset directories
...
又一类笔误：中间某一级目录被改过名，引用没跟着改。
Tang-Nano-1K/Nano_1K_examples/ -> Tang-Nano-1K/examples/
maixpy assets/dk_board/ -> assets/hardware/
Tang Nano-4K/ -> assets/Nano-4K/
这类前两条规则都够不着：按文件名匹配是多候选（同名图在别的产品
目录下也有），按整段尾路径匹配又因为中间那级对不上而失败。
改用「锚定最长存在前缀 + 匹配最深后缀」：先从左往右找仍然存在的
最长目录前缀作为锚点，再在锚点下按尽可能深的路径后缀唯一匹配。
8 处全部零歧义。断链 60 -> 52。
2026-10-07 21:08:00 +08:00
zepan
b668c2c952
fix(docs): repair wrong '../' depth in image references
...
spmod 等页面把 ../assets/... 写成了 ../../assets/...，多了一级。
判定方式不是靠文件名撞运气，而是整段尾路径精确匹配：沿页面的各级
父目录向上找，看哪一级拼上 assets/spmod/spmod_bt/back.jpg 这样的
完整尾路径能命中。命中多处时取最近的祖先——依据是同目录下能正常
显示的页面（spmod_ethernet/fpc/weather）用的就是 ../assets/...。
13 组多处命中里 11 组是逐字节相同的副本，取哪个都一样；另 2 组是
同一张图的不同分辨率，按同目录惯例取 en/maix 下的高清原图。
断链 76 -> 60。
2026-10-07 21:02:49 +08:00
zepan
47089a4329
fix(docs): repair 42 more broken image paths by unique-name matching
...
接着上一轮，按「候选在仓库中唯一」继续批量修复素材搬家遗留的断链：
- 页面自身目录内的子目录名写错 12 处
assets/lc3a -> assets, assets/images -> assets/image,
assets/lbook -> assets/lbook4a, 以及文件名大小写笔误
- maixface 24 处：文档在 docs/hardware/maixface/{zh,en}/，素材却留在
docs/hardware/zh/maixface/assets/（目录层级顺序相反），位移规则统一
- 其余跨目录唯一匹配 6 处
护栏：纯数字或过短的文件名（11.png 这类）即使全仓库唯一也不自动匹配，
因为很可能只是撞车——实测确有一例指向了毫不相关的文档。
断链 118 -> 76，基线同步更新；新引入 0 处（构建产物复核过）。
2026-10-07 20:54:20 +08:00
zepan
66300f5dd7
fix(tools): resolve site-absolute image paths the way teedoc does
...
构建产物核验发现检查器有 3 个误报，成因是绝对路径解析不全：
- /news/... 由 blog 插件发布，site_config 的 route 里没有登记
- 不匹配任何路由的绝对路径，teedoc 是按「该文档所属路由的根」解析，
而不是站点根。例如 /assets/x.jpg 出现在 docs/soft/maixpy/en/ 的
页面里，实际指向 docs/soft/maixpy/assets/x.jpg
补上这两条回退后，断链 121 -> 118，基线同步更新。
拿构建产物复核：118 项里 112 项在生成的网站里确实取不到。
2026-10-07 20:41:00 +08:00
zepan
2821a421bc
ci: check that referenced images exist; document shallow clone
...
断链图片一直在悄悄累积（本次清理前有 230 处），而且线上看不出来：
teedoc-upload 只上传不删除对象存储里已移除的文件，旧副本把断链盖住了，
所以页面看起来正常。CI 里也从来没有任何链接检查。
- tools/check_image_links.py：只认 markdown ![]() 与 <img src>，
先剥离代码块以免把 `convert in.jpg out.jpg` 这类示例当成引用，
并按 site_config 的 route 解析站点绝对路径。
- tools/known_broken_images.txt：当前仍存在的 121 处已知断链基线。
CI 对不在基线中的断链报错，基线只许减不许增。
- .github/workflows/check_links.yml：push 与 PR 均运行。
- README：建议 --depth=1 浅克隆并解释原因——文档站的历史里保留了
每张图的所有旧版本（约 1GB），而贡献者只需要当前版本。
2026-10-07 01:01:33 +08:00
