文档系统

相关源文件

• .github/workflows/check-broken-links.yml
• docs/.yarnrc.yml
• docs/Makefile
• docs/docs/versions/v0_2/deprecations.mdx
• docs/docs/versions/v0_2/index.mdx
• docs/docs/versions/v0_2/migrating_astream_events.mdx
• docs/docusaurus.config.js
• docs/ignore-step.sh
• docs/package.json
• docs/scripts/append_related_links.py
• docs/scripts/check-broken-links.js
• docs/scripts/generate_api_reference_links.py
• docs/scripts/partner_deps_list.py
• docs/scripts/resolve_local_links.py
• docs/sidebars.js
• docs/src/theme/DocItem/Paginator/index.js
• docs/src/theme/Feedback.js
• docs/static/js/google_analytics.js
• docs/vercel.json
• docs/vercel_requirements.txt
• docs/yarn.lock

文档系统涵盖了用于构建、维护和部署 LangChain 综合文档网站的基础设施、工具和流程。该系统处理 python.langchain.com 上主要文档的内容生成、自动化处理、部署和用户体验功能。

有关 API 参考生成的具体信息，请参阅 API 参考生成。有关辅助开发工作流程的 CLI 工具和模板，请参阅 CLI 和模板。

架构概述

文档系统基于 Docusaurus 构建，采用多阶段构建流程，将源内容转换为具有增强功能的生产就绪型网站。

来源：docs/Makefile、docs/docusaurus.config.js、docs/vercel.json

网站基础设施

文档网站使用 Docusaurus 3.5.2 构建，配置用于处理 LangChain 复杂的文档结构和集成需求。

核心配置

docs/docusaurus.config.js 中的主要 Docusaurus 配置定义了

组件	配置	目的
站点元数据	title: "🦜️🔗 LangChain"	品牌和搜索引擎优化
URL 结构	url: "https://python.langchain.ac.cn"	生产部署
主题支持	themes: ["@docusaurus/theme-mermaid"]	图表渲染
搜索集成	algolia: { appId: "VAU016LAWS" }	全文搜索

侧边栏导航结构

docs/sidebars.js 中的侧边栏配置将内容组织成逻辑部分

来源：docs/docusaurus.config.js:127-311、docs/sidebars.js:21-469

构建与部署过程

文档构建过程由 Makefile 管理并经 Vercel 部署的多个协调阶段组成。

多阶段构建管道

docs/Makefile 中的关键构建目标

目标	目的	关键操作
install-py-deps	依赖设置	python3 -m venv .venv、uv pip install
generate-files	内容生成	功能表、外部内容获取
render	Notebook 处理	Jupyter 到 markdown 转换
generate-references	API 增强	自动化 API 参考链接
vercel-build	生产构建	包含 API 文档集成的完整管道

部署配置

Vercel 部署在 docs/vercel.json 中配置，包含

• 构建命令：yarn build
• 输出目录：build
• 条件构建：通过 ignore-step.sh 根据内容更改进行智能构建
• URL 重写：版本路由和旧版 URL 处理
• 重定向：针对已移动内容的 SEO 友好型 URL 管理

来源：docs/Makefile:1-88、docs/vercel.json:1-166、docs/ignore-step.sh:1-34

内容处理与自动化

文档系统采用多个自动化内容处理脚本，以增强用户体验并保持一致性。

API 参考链接生成

generate_api_reference_links.py 脚本自动将 API 文档链接注入代码示例

该脚本支持 LangChain 和 LangGraph 生态系统，并采用不同的 URL 模式

• LangChain：https://python.langchain.ac.cn/api_reference/{pkg}/{module}/{path}.html
• LangGraph：https://github.langchain.ac.cn/langgraph/reference/{namespace}/#{module}.{class}

内容增强功能

脚本	目的	实现
append_related_links.py	添加集成指南	处理集成页面，添加概念/操作方法链接
resolve_local_links.py	外部链接解析	更新外部内容的相对链接
notebook_convert.py	Jupyter 处理	将 Notebook 转换为文档格式

来源：docs/scripts/generate_api_reference_links.py:1-364、docs/scripts/append_related_links.py:1-85

质量保证与验证

该系统包含自动化质量保证工具，以维护文档完整性。

断链检测

自动化链接检查通过 GitHub Actions 和 JavaScript 工具实现

.github/workflows/check-broken-links.yml 中的工作流程使用 @langchain/scripts 包运行链接验证，具有可配置的超时和重试设置。

构建优化

ignore-step.sh 脚本实现了智能构建跳过

• 生产构建：master、v0.1、v0.2、v0.3rc 分支始终进行
• 开发构建：使用 git 日志分析检查 docs/ 目录中的更改
• 更改检测：检查最近 50 次提交以查找与文档相关的更改

来源：.github/workflows/check-broken-links.yml:1-26、docs/ignore-step.sh:1-34、docs/scripts/check-broken-links.js:1-8

用户体验功能

文档系统包括基于 Docusaurus 构建的几项增强用户体验功能。

反馈收集系统

docs/src/theme/Feedback.js 中的反馈系统提供

主要功能

• 速率限制：基于 Cookie 的重复提交预防（24 小时有效期）
• 数据隐私：收集 IP 地址并进行 UUID 跟踪
• 可选增强：后续评论收集
• 项目范围：LANGCHAIN_PROJECT_NAME = "langchain_py_docs"

增强导航

docs/src/theme/DocItem/Paginator/index.js 中的分页器增强功能集成了

• 反馈组件：每页反馈收集
• 讨论集成：Giscus 支持的 GitHub 讨论
• 上下文导航：标准 Docusaurus 分页

搜索与分析

功能	实现	配置
搜索	Algolia DocSearch	appId: "VAU016LAWS"、indexName: "python-langchain-latest"
分析	Google Analytics	多个跟踪 ID，用于全面指标
性能	自定义 webpack 配置	处理 polyfill、模块解析

来源：docs/src/theme/Feedback.js:1-298、docs/src/theme/DocItem/Paginator/index.js:1-27、docs/docusaurus.config.js:299-325