跳到主要内容
Ed. notes

内容加载:把 Markdown 变成 Document

长文 · 2026-11-11 · 合集第 5 / 11 篇

  • Python
  • Markdown
  • 内容管线
第 5 / 11 篇 · 查看全部章节 → 当前:内容加载:把 Markdown 变成 Document

结论

RAG 的第一步不是切片,而是把文件系统里的 Markdown 收敛成统一的 Document。load_documents() 负责过滤草稿、跳过目录文件、解析 slug、检查唯一性;下游切片只接收 Document,不关心文件来自笔记还是长文。

问题与设计

索引不能扫描整个仓库:目录页不是文章,草稿不能进入检索,slug 冲突会让引用 URL 指向错误内容。前后端又使用不同语言,无法直接共享解析代码,只能共享行为规则。

规则与前端保持一致:

  • 笔记 slug 来自文件名;<slug>/index.md 取目录名。
  • 长文 slug 必须写在 frontmatter。
  • draft: true 不进入索引。
  • 00-目录.md 在扫描阶段跳过。
  • slug 必须是小写 kebab-case,且全局唯一。
  • 站内 URL 统一为 /notes/{slug}。

关键代码

统一的数据结构:

@dataclass(frozen=True)
class Document:
    slug: str
    kind: str
    title: str
    url: str
    body: str
    date: str
    tags: tuple[str, ...]
    file: Path

笔记和长文的 slug 来源不同:

# 笔记
slug = path.parent.name if path.name == "index.md" else path.stem

# 长文
slug = metadata.get("slug")
if not isinstance(slug, str) or not slug.strip():
    raise ContentError(f"{path}: 长文必须在 frontmatter 中提供 slug")

过滤与校验集中在 _parse_document():

if metadata.get("draft") is True:
    return None

if not SLUG_PATTERN.fullmatch(slug):
    raise ContentError(f"{path}: slug 必须是 kebab-case,实际为 {slug!r}")

title = metadata.get("title")
if not isinstance(title, str) or not title.strip():
    raise ContentError(f"{path}: 缺少 title")

所有文档加载后检查 slug 冲突:

def _ensure_unique_slugs(documents: list[Document]) -> None:
    seen: dict[str, Path] = {}
    for document in documents:
        if document.slug in seen:
            raise ContentError(
                f"slug 冲突:{document.slug} 同时出现在 {seen[document.slug]} 和 {document.file}"
            )
        seen[document.slug] = document.file

验证

当前内容目录的装载结果:

documents: 18
kinds: {'note': 8, 'article': 10}

测试用临时目录验证了三种 slug 来源:

articles/series/05-x.md   → frontmatter slug
notes/magpie.md           → magpie
notes/nested/index.md     → nested

同时覆盖了草稿与 00-目录.md 被跳过、长文缺 slug 报错、foo.md 与 foo/index.md 冲突拒绝继续。

边界

  • 这里只保证索引所需字段、slug 和唯一性;完整的 frontmatter 校验仍由前端构建前的内容校验负责。
  • Python 的 YAML parser 可能把日期解析成 date 对象,代码要同时兼容日期对象和字符串。
  • draft 只在严格布尔 True 时过滤,字符串 "true" 不会生效。
  • 当前使用 rglob("*.md") 递归扫描,比前端“笔记一级、文章系列一级”的范围更宽;目录结构变深时要重新核对两边行为。

下一篇看切片:Document 怎样按 Markdown 结构变成可检索的 Chunk。