给 LLM 准备的文档站：mdjango 的工程化改造清单

摸鱼小队长 内容创作者 2026-09-22 44 阅读

先说结论

  • mdjango 是一个面向文档站的 Django 可复用插件：它把一棵 Markdown 内容树自动渲染成带导航、搜索、目录、深浅色模式，并额外输出 llms.txt、llms-full.txt 机器可读工件。
  • 它对 LLM 友好不是靠隐藏提示词，而是靠显式结构化：页面都有 .md 备用版本、内容树层级固定、路由稳定、前端元数据有限且可预期。
  • GEO（生成引擎优化）在工程侧最先能落地的动作，不是堆关键词，而是让抓取方拿到干净的 Markdown 和统一的机器索引。
  • 不绑定 Django 的通用改造清单同样可复用：文档源 Markdown 化、目录与 URL 对齐、显式 title/description、提供 llms.txt 与静态导出、接入 CI 校验。
  • mdjango 官方没有宣称这是所有网站的通用优化方案：它明确把自己定位成“30 分钟可配置好的 drop-in 文档 app”，而不是内容营销或 SEO 框架。

为什么从 mdjango 说起

这次我实际读到的两个一手来源，是 mdjango 的官方文档站和 GitHub 仓库。

官方文档站首页写明：

mdjango is a Django app that allows you to quickly setup a decent technical documentation site. You install it, point it at a directory of markdown files, the Content tree, and include its URLs under a prefix. Your running Django process then serves a documentation site at that prefix: header, section navigation, article, table of contents, prev/next links, full-text search, dark mode, and the llms.txt family of machine-readable artifacts.

这段官方描述说明白了几件事：输入是 Markdown 内容树，输出是一个完整文档站，并且把 llms.txt 家族称为 machine-readable artifacts。注意，这里说的是“机器可读工件”，不是简单的 sitemap 或 SEO 页面。这个定位，正好适合我们讨论“给 LLM 准备的文档站”。

同一页还提到：站点本身就是 mdjango 挂载自己内容的默认效果，页面头部有 .md 备用链接。官方文档写明：

Every page has a .md alternate, linked from the header.

这句话很关键，它意味着抓取方不需要猜 URL，也不需要从 HTML 里剥正文，直接拿 .md 就能获得干净的 Markdown 源。这对 LLM 抓取非常友好。

GitHub 仓库 README 的表述更简短：

A reusable, drop-in markdown-documentation Django app. Point it at a tree of markdown and get a themed documentation site — served at runtime, or exported static with mdjango_build. One opinionated house style; seven CSS seeds to make it yours.

官方 README 还标注了当前状态：

Status: 0.1.0 — the first public release, on PyPI (pip install mdjango); a 0.x line, so the API may still change.

这是官方数据：版本号为 0.1.0，且官方提示 0.x API 仍可能变化。另一个官方数据是“30 分钟可配置好”，来自官方文档站的原话：

mdjango is meant to be a drop-in app that you can setup in 30 mins.

官方说的：机器可读设计在哪里体现

从两个一手来源里，可以明确归纳出官方已经写清楚的设计点。

1. llms.txt 与 llms-full.txt

官方文档站页面头部直接列出了 llms.txt 和 llms-full.txt 两个入口。网站描述中使用的是 “the llms.txt family of machine-readable artifacts”。这说明官方把这两个文件视作一组产物，而不是后来附加的 SEO 补丁。

不过，官方文档站和 GitHub README 里，都没有给出 llms.txt 官方规范的链接，也没有详细解释这两个文件内部的字段格式。因此，我只能确认 mdjango 会生成这两个文件，至于它们是否完全符合某个社区规范，本次未能核实。

2. 每个页面有 .md 备用

官方文档站写明 “Every page has a .md alternate, linked from the header.”。这属于官方文档中能查到的行为描述。它不是配置项，而是默认行为。抓取方拿到 .md 后，可以跳过导航、页脚、搜索框等页面噪音。

3. 内容树层级固定为三层

GitHub README 给出了内容树规则，官方写明：

Convention-driven, capped at three levels (section → subsection → page)

并且：

A fourth level is a build error.

这是官方明确约束：内容树最多三层，第四层会触发构建错误。层级固定，意味着路由和导航结构可预期，LLM 爬虫不需要猜测深度。

4. 主题风格固定，只有七个 CSS 种子

官方 README 中的示例 CSS 变量如下：

:root {
  /* surface ramp: ground -> hairline */
  --background: #ffffff;
  --border: #e2e6ec;
  /* text ramp: full emphasis -> lowest emphasis */
  --foreground: #14181f;
  --foreground-subtle: #7b8494;
  --accent: #2f6df6; /* optional; defaults to --foreground (monochrome) */
  --font: "Inter", system-ui, sans-serif;
  --font-size: 15px;
}

官方用 “seven CSS seeds” 来描述可设置项。也就是说，你能改的只有色阶两端、强调色、字体、根字号等少数变量，中间色阶由算法计算并锁定。官方对此的解释很直接：这是刻意设计，目的就是避免无尽自定义带来不稳定的页面结构。稳定的 HTML 结构和类名，对机器抓取也有好处，因为版面不会因为主题微调而大幅变化。

工程上怎么做：一次最小安装与内容树

下面是基于官方 GitHub README 的安装与配置示例。需要注意，以下代码是官方 README 中给出的示例，不是我的推断。

# settings.py
INSTALLED_APPS = [
    # ...
    "django_cotton",  # mdjango 的模板使用 cotton；这一行会自动配置其 loader
    "mdjango",
]

MDJANGO_CONTENT_DIR = BASE_DIR / "content"  # 你的 Markdown 内容树（必填）
MDJANGO_BRAND = "acme"                        # 品牌词 / <title>
MDJANGO_VERSION = "v2.3.0"                    # 展示用版本字符串
MDJANGO_GITHUB_URL = "https://github.com/acme/acme"

路由挂载方式：

# urls.py
urlpatterns = [
    path("docs/", include("mdjango.urls")),
]

官方 README 给出的内容树结构示例是：

content/
  _index.md               # 可选文档首页，挂载在根路径
  about.md                # 可选散页 -> /docs/about/
  getting-started/        # 一个 section
    _index.md             # 仅 frontmatter：section 标题/权重
    quickstart.md         # 页面 -> /docs/getting-started/quickstart/
  guides/
    networking/           # subsection：只是导航组，不是页面
      _index.md           # 仅 frontmatter：subsection 标题/权重
      ingress.md          # -> /docs/guides/networking/ingress/
      secrets.md

在工程实践中，这套结构的意义是：目录树即站点地图，文件名即 URL 路径。官方没有说“每个页面都必须写 description”，但 frontmatter 支持的字段已经在 README 中写明：

Frontmatter (a flat block of scalars): title, weight (int, orders nav), draft (bool, hidden unless DEBUG / MDJANGO_INCLUDE_DRAFTS), description.

也就是说，title、weight、draft、description 是官方支持的前端元数据字段。draft 的可见性取决于 DEBUG 或 MDJANGO_INCLUDE_DRAFTS，官方文档也提示 caching 和草稿可见性在关闭 DEBUG 后会改变。这在生产环境尤其要注意：你本地以为隐藏的草稿，可能到线上会按缓存规则暴露或不可见。

不绑定 Django 的通用改造清单

下面这份清单是我从 mdjango 的设计中提炼出来的判断，不是官方推荐。它适用于任何想提高 LLM 可读性的技术文档站，不管你是否用 Django。

1. 文档源优先 Markdown

Markdown 比富文本更易被 LLM 解析。尽量让每个页面都有对应的 .md 源文件或可稳定访问的 Markdown 版本。mdjango 直接以 Markdown 内容树为唯一事实源，这比“先维护 HTML，再反向提取文本”更可靠。

2. 提供机器可读索引

至少输出一个 llms.txt，列出所有文档入口、标题和说明；如果需要完整正文抓取，可以再提供 llms-full.txt。本次来源中我只确认 mdjango 生成这两个文件，没有看到其它社区实现细节，所以建议结合你自己的技术栈选择生成方式。

3. 控制层级与 URL 稳定性

层级不要超过三层，URL 与目录结构保持一致。mdjango 官方把第四层设成构建错误，这虽然严格，但确实能防止随意嵌套，间接提升 URL 可预测性。

4. 显式 frontmatter 元数据

每个页面都应显式声明 title 和 description。如果是草稿，要有明确的开关，并清楚它在生产环境是否可见。不要让机器抓取到空标题或半成品页面。

5. 保留稳定的模板与结构

不要频繁改变 HTML 结构、类名和导航逻辑。mdjango 通过固定 house style 和有限 CSS 变量来达到这一点。实践中，你也可以通过限制主题自定义范围，换取抓取稳定性。

6. 支持静态导出与 CI 校验

mdjango 支持 mdjango_build 静态导出，官方 README 也提到有 Validate content in CI 文档。工程上，我会把静态导出和内容校验放进 CI 流程，例如使用 GitHub Actions 跑构建与检查，避免坏链接或缺失 llms.txt 上线。这里链接到 GitHub Actions 只是为了说明一种常见 CI 工具，不代表 mdjango 官方要求或推荐它。

7. 让每一页都能被单独抓取

除了列表页，单个页面也要有稳定 URL，并且能被直接访问。mdjango 给每个页面生成 prev/next 链接，但更重要的是，每个页面在内容树中都有确定位置，爬虫不需要通过搜索才能发现。

我的判断：谁适合用它，谁应该自己搭

mdjango 非常适合已有 Django 项目、需要快速挂一个技术文档站、且不想在样式和结构上反复折腾的团队。官方明确说它是 “drop-in app”，目标就是 30 分钟配置完成。如果你正好需要 llms.txt、.md 备用、固定层级、静态导出，这会是一个很合适的起点。

但它也有明显边界。官方原文写得比较直白：

If you need more customizing, you’re better of building your own docs feature in your current Django app, or using another off-the-shelf tool that allows for more customization.

也就是说，如果你需要完全自定义布局、复杂权限、动态内容渲染或非 Markdown 内容，mdjango 可能不是最佳选择。此时与其在它的框架里打补丁，不如自己实现一个轻量文档管线。

从 GEO 角度看，mdjango 给我们的启示是：先保证机器能吃到的内容质量，再谈排名和曝光。很多团队做 LLM 优化时，盯住的是“让 AI 提到我”，却忽略了 AI 抓取时拿到的可能是导航、弹窗、广告和残缺正文。把文档站做成干净、结构化、可静态导出的形态，是比追逐提示词更长期有效的事。

这次没核实的

  • llms.txt 官方约定的一手出处未能核实：本次来源中只确认 mdjango 会输出 llms.txt 与 llms-full.txt，但没有提供规范链接或格式说明。我没有自行补充外部 URL。
  • llms-full.txt 的内部格式与字段未能核实：官方只提到这是 machine-readable artifacts 的一部分，没有展开细节。
  • mdjango 0.1.0 之后的 API 稳定性无法确认：官方声明 0.x 线可能变化，但未给出具体路线图。
  • mdjango 对传统搜索引擎的 SEO 效果未能核实：官方文档没有提供相关数据或对比测试。
  • 静态度量指标：例如 LLM 抓取成功率、抓取耗时等，本次来源中没有官方数据，我也没有能力从这些材料中推算，因此不作猜测。

参考来源

  1. mdjango 官方文档站（一手来源，2026-09-20 官方页面）
  2. mdjango GitHub 仓库（一手来源，官方 README）
  3. GitHub Actions 功能页（仅作为 CI 工具举例，非 mdjango 官方来源）
# 教程# 知识

评论区

0 条评论

登录后可评论。

摸鱼小队长 44 阅读