LLM Wiki

Appearance

Built 26/04/16 07:49commit 209d49d

Raw Markdown Build-Safe Linking ​

中文 | English

摘要 ​

一个 markdown 文件在内容上可能完全正确，但被搬进 raw/ 之后仍然可能把本地 wiki 构建炸掉。最常见的坑，是直接保留上游 README 里的仓库相对图片或文档链接，然后让 VitePress 按当前仓库而不是按原始来源仓库去解析这些路径。

现象 ​

新收录的 raw markdown 在纯文本里看起来没问题，但 pnpm docs:build 会在 ingest 后失败，报错通常像这样：

text
[vite]: Rollup failed to resolve import "docs/assets/banner.jpg" from ".../raw/.../source.md"

根因 ​

raw 文件的“内容意义”应该尽量保持不变，但它内部带着的相对资源链接并不是脱离上下文就永远成立的。像 docs/assets/banner.jpg、README.zh-CN.md、SELF_HOSTING.md 这样的路径，一旦被复制到另一个仓库里，就不再指向原来源树。静态站点构建器可能会把它们当成当前仓库内的本地 import 或 markdown 目标，于是一个看起来无害的 source snapshot 就变成了渲染期故障源。

确认模式 ​

  1. 只要加入某个 markdown raw source，构建就立刻开始失败。
  2. 报错指向该 raw 文件中的相对资源或文档路径。
  3. 这个路径在上游仓库里存在，但在本地 wiki 仓库的相同相对位置并不存在。
  4. 把该路径改成稳定的外部 URL，或改成仓库内镜像资源后，构建恢复通过。

实用修复 ​

快速稳住 ​

把上游相对引用改成稳定的公网 URL：

  • 图片和 svg 资源 -> https://raw.githubusercontent.com/...
  • 文档链接 -> https://github.com/.../blob/...

这样既能跨机器工作，也避免把机器相关的本地文件系统路径写进仓库。

更耐久的方案 ​

如果这个来源后续变得很重要，就把必要资源镜像到 wiki 仓库里，再把 raw markdown 改指向这些镜像副本。这样可以减少对上游路径稳定性和在线网络抓取的依赖。

经验规则 ​

  • 不要为了修构建而引入 /Users/...、C:\...、file:///... 这类绝对本地文件系统路径。
  • 优先做“最小语法修复”，既保留源意义，又保证文件可渲染。
  • 要区分“跨机器可用的公网绝对 URL”和“只在本机有效的绝对路径”。前者通常可移植，后者通常不可移植。
  • 如果某个 raw markdown 要做很多清洗才能安全渲染，可以优先保留核心文本，裁掉非关键的装饰性资源。

例子 ​

在收录 Multica 时，导入的 README 带有 docs/assets/banner.jpg 和 SELF_HOSTING.md 这类上游相对引用。文件被复制到 raw/github/multica-ai/multica.md 后，本地 VitePress 构建开始尝试在 llm-wiki 仓库内解析这些路径，并因此失败。把它们改写成 GitHub raw/blob URL 后，构建恢复稳定，同时没有改变来源本意。

相关页面 ​