langchain-ai/docs

解决的问题

为大型多项目生态系统编写和维护文档是件麻烦事。该仓库提供了一个单一的自动化流水线，将源文件转换为精美的文档网站（docs.langchain.com），用于 LangChain、LangGraph、LangSmith 及相关工具。它还为贡献者提供了一组命令，用于在本地预览、构建和检查文档，从而在发布前捕获错误。

工作原理

内容以 Markdown 文件（.md 和 .mdx）的形式存在于 src/ 文件夹中，这是您唯一应该编辑的地方。构建脚本预处理这些文件，并将可部署的版本输出到 build/ 文件夹。该文件夹是 Mintlify（托管平台）实际提供服务的目录。仓库还包含辅助脚本、包元数据以及控制导航和设置的配置文件（docs.json）。

对于日常工作，您可以使用 Make 命令：make install 设置依赖项，make dev 启动带有实时重载的本地服务器，make build 生成静态文件，make test 运行测试套件。还有一个 docs 命令行工具，可以将旧格式的 Markdown 或 Jupyter 笔记本转换为 Mintlify 友好的格式（包括从 MkDocs 或 Docusaurus 项目），并在更新交叉链接的同时移动文件。为了保持高质量，仓库包含两个 linter：codespell 捕获散文中的拼写错误，vale 根据规则文件检查风格。README 还解释了如何排查常见的 Mintlify 问题，例如因从错误目录运行 Mintlify 而导致的链接损坏。

适用对象

LangChain 文档的贡献者——任何想在 docs.langchain.com 上编写、编辑或修复页面的人。它也对需要管理构建过程、迁移旧文档或确保链接和风格保持一致性的维护者有用。README 假设您熟悉命令行和 Git，但它清楚地解释了所有步骤。

亮点

• 单一事实来源：编辑 src/，运行命令，Mintlify 从 build/ 部署。
• 通过热重载在本地预览（make dev）。
• 通过 make broken-links-with-anchors 自动检查链接（包括锚点）。
• 迁移工具，将现有文档从 MkDocs 或 Docusaurus 转换为 Mintlify 格式。
• 拼写检查（codespell）和风格检查（vale）以保持散文一致性。
• 清晰的故障排除部分，涵盖常见的 Mintlify 陷阱，如 .venv 解析错误。