内容加载:把 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。