LLM Wiki

Appearance

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

Raw Markdown Build-Safe Linking ​

中文 | English

Summary ​

A markdown file can be substantively correct yet still break the local wiki build when transplanted into raw/. The common trap is carrying over repo-relative images or document links from an upstream README, then letting VitePress interpret them inside the current repository instead of the source repository they originally came from.

Symptom ​

A new raw markdown source looks fine in plain text, but pnpm docs:build fails after ingest with a resolver error such as:

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

Root Cause ​

The raw file is immutable in substance, but its embedded relative asset links are not context-free. Once copied into another repository, paths like docs/assets/banner.jpg, README.zh-CN.md, or SELF_HOSTING.md no longer point at the original source tree. A static-site builder may treat them as local imports or local markdown targets in the current repo, which turns an otherwise innocent source snapshot into a render-time failure.

Confirmation Pattern ​

  1. The build starts failing immediately after adding a markdown raw source.
  2. The error points to a relative asset or document path inside that raw file.
  3. The referenced path exists in the upstream repository, but not at the same relative path inside the local wiki repository.
  4. Replacing that path with a stable external URL or a local mirrored asset makes the build pass again.

Practical Fixes ​

Fast Stabilization ​

Replace upstream-relative references with stable public URLs:

  • image and svg assets -> https://raw.githubusercontent.com/...
  • document links -> https://github.com/.../blob/...

This keeps the raw file readable across machines and avoids machine-specific filesystem paths.

More Durable Option ​

If the source becomes strategically important, locally mirror the required assets into the wiki repository and rewrite the raw markdown to point at those mirrored copies. This removes dependence on upstream path stability and live network fetches.

Rules Of Thumb ​

  • Never repair build failures by introducing absolute local filesystem paths such as /Users/..., C:\..., or file:///....
  • Prefer the smallest syntax-only repair that preserves source meaning and keeps the file render-safe.
  • Distinguish cross-machine-safe absolute URLs from machine-specific absolute paths. Public HTTPS URLs are usually portable; local filesystem absolutes are not.
  • When a raw markdown file still needs substantial cleanup to render safely, consider keeping the essential text while trimming non-essential decorative assets.

Example Incident ​

During Multica ingest, the imported README contained upstream-relative references such as docs/assets/banner.jpg and SELF_HOSTING.md. After the file was copied into raw/github/multica-ai/multica.md, the local VitePress build tried to resolve those paths inside llm-wiki and failed. Rewriting them to GitHub raw/blob URLs restored build stability without changing the source meaning.