ClickHouse 开发者文档迁移至 Mintlify 平台并完成改版

在 ClickHouse，我们将开发者文档视为一款产品，并始终在探索如何为客户和开源社区不断改进它。

今天，我们宣布 clickhouse.com/docs 在 Mintlify 上全新改版。Mintlify 是一个每月服务上千万开发者的智能知识平台，为 Anthropic、Microsoft、Coinbase、Perplexity 以及如今的 ClickHouse 等公司的帮助中心、支持中心和开发者文档网站提供支持。

为什么我们要迁移平台？

仅在过去一年里，开发者文档领域就发生了巨大变化。如今，超过一半的文档流量来自编程智能体（coding agents），而非纯人类访问。这种转变意味着对文档网站的功能要求也发生了改变。我们之前的平台 Docusaurus 虽然多年来表现良好，但它在设计时仅考虑了人类读者，那时“智能体”还远未占据我们的终端。

我们选择与 Mintlify 合作搭建新文档网站，是因为该平台从底层设计起就同时兼顾了人类和智能体的需求。迁移到新平台后，我们能为您提供更优质的开发者文档体验，实现更快的迭代，并让我们能专注于自己真正热爱的事业——即竭尽所能为您提供最佳的文档体验。

有哪些变化？

打开新版文档，映入眼帘的是全新的着陆页和 UI 界面。我们将搜索和“询问 AI”（Ask AI）功能置于核心位置，这是顺应访问模式变化而做出的刻意选择，从而帮助您更快找到所需答案。现在，您可以跨文档、博客甚至 GitHub issues 进行全局搜索，也可以通过“询问 AI”获取更具针对性的解答。

对于希望让智能体直接对接文档以获取最新解答的用户，我们在着陆页提供了配置指南和一键命令，用于搭建文档 MCP 服务器。该服务器配备了内置工具，允许智能体跨全站搜索，使用类 Shell 命令读取并导航网站的虚拟文件系统，还能在智能体发现页面出现错误、过时、表述不清或内容缺失时向我们的团队发送反馈。

配合 Claude Code 搭建文档 MCP 服务器非常简单，只需在终端运行以下命令：

网站现在会自动检测 Agent 发出的请求，并向其返回 Markdown 而非 HTML 格式，以便 Agent 能更快地处理内容，同时消耗更少的 Token。

过去我们常收到反馈，称文档难以导航，因为顶部导航针对不同产品模块和用户目标设置了各种多级下拉菜单。在新版网站中，我们简化了导航，将开源版 ClickHouse 和 ClickHouse Cloud 共有的核心数据库功能文档，与 Cloud 专属的产品文档分离开来。

核心数据库文档现已根据不同的使用目标进行分类：

Cloud、ClickStack、Managed Postgres 等特定 ClickHouse 解决方案的文档现在统一放在“Solutions”标签页下，并采用类似的分类结构。此外，我们将集成文档拆分成了三个独立部分：ClickPipes、语言客户端和连接器。

围绕明确的用户目标来组织各产品模块的文档，使我们能够为你提供更一致的阅读体验。

我们的 API 文档用户可能还记得，以前查看 API 时会被跳转到另一个平台。现在无需跳转了，你可以直接在 Cloud 和 ClickStack 的文档中，访问由 OpenAPI 规范生成的文档。如果在 API 资源管理器中点击“Try it”按钮并填入凭证，网站会安全地展示 ClickHouse 服务的响应结果，让你无需离开浏览器即可快速探索 API。

无论对读者还是对我们，Mintlify 平台都带来了多项易用性提升。现在，每个页面都提供复制为 Markdown 格式、直接查看 Markdown 源码的选项，以及配置 MCP 服务器的快捷链接。对于习惯离线阅读的用户，我们也增加了将页面下载为 PDF 文件的功能。

我们的文档很早以前就加入了反馈组件，但新平台在追踪和处理反馈的体验上做了进一步优化。现在，我们可以对每条反馈进行分类，添加内部备注，并追踪其处理进度。

作为一家全球分布、远程优先的公司，我们是 Slack 的重度用户。现在我们可以通过 Slack 机器人更新文档，再配合 Notion 风格的可视化编辑器，这将加快我们为你更新文档的速度。我们也非常期待使用 Mintlify 的 automations 功能来实现文档内容的自动维护。

活跃的社区成员可能知道，我们的文档过去一直分散在两个代码仓库中：ClickHouse/ClickHouse（存放参考文档）以及 ClickHouse/clickhouse-docs（存放指南、教程和产品文档）。现在，我们已将所有文档迁回至核心开发仓库。

随着各类智能体将文档视为事实来源（source of truth），保持文档与代码变更的同步变得比以往任何时候都更加重要。

这一举措让我们能将文档与代码，以及编写代码的工程师和社区贡献者紧密联系在一起，从而更容易通过自动化的 AI 审查来发现文档与代码脱节的问题。这也有助于我们在统一的地方为社区提供服务，当你想反馈文档问题时，不再需要额外切换上下文。此外，这也意味着你对文档的贡献现在会像代码贡献一样，将你的名字记录在 system.contributors 表中。

在开源软件中，文档是备受重视却常被忽视的一环。对 ClickHouse 而言，这也是进行首次贡献的理想切入点。我们期待看到更多首次贡献者通过提交一个小小的、但同样受到认可的文档 PR，踏入开源世界。

我们的文档目前提供英语、日语、韩语、简体中文和俄语版本。随着新网站的上线，我们将本地化支持扩展到了巴西葡萄牙语、西班牙语、法语和阿拉伯语。虽然我们已尽力确保这些语言的 LLM（大语言模型）翻译达到较高水准，但仍欢迎社区中的母语者参与贡献，以进一步提升翻译的准确度。

由 Alexey Milovidov 贡献

ClickHouse 26.6 版本为习惯使用终端的用户带来了一项重大的易用性改进：现在可以直接在客户端中搜索并阅读参考文档。只需输入 help <topic> 或 \h <topic> 即可立即查看相关文档。此外，你也可以通过 ClickHouse Reference 或访问运行中服务器的 /docs 路径来获取文档。

这一功能得益于新系统表 system.documentation 的引入。尽管 system.functions 和 system.settings 等表此前已内嵌了相关文档，但仍有一些未能覆盖的领域。现在，针对表引擎、数据库引擎、数据格式、聚合函数组合器、字典布局、字典数据源、跳数索引类型以及磁盘类型，我们均添加了新的系统表，每张表都包含了各自的说明文档。

欢迎在 26.6 版本发布会 中观看 Alexey 演示该功能（https://www.youtube.com/live/-NmqMH9y4EY?si=ZAIEQmVVAOlii257&t=596）。

期待你的反馈

欢迎分享您对新网站的看法与反馈。您可以通过每个文档页面底部的反馈表单（点赞或踩按钮）以及“提交 Issue”按钮联系文档团队，或者直接通过我们的 community slack 交流。您的反馈对我们打造更好的文档体验帮助极大（https://clickhousedb.slack.com/join/shared_invite/zt-44wvsqbjb-53ggHzNoaCyG5k3dFDyOQA#/shared-invite/email）。