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

本文字数15510估计阅读时间39 分钟作者Shaun Struwig, Dominic Tran and Alexey Milovidov编者按本文译自 ClickHouse 原博客。 原文围绕「开发者文档向 AI 友好型架构的演变」展开。随着编程智能体成为文档访问的主力文档平台的选型正从纯展示向数据化与智能化转型。ClickHouse 的迁移实践展示了技术文档如何通过架构调整提升在 AI 时代的检索效率。在 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 服务器非常简单只需在终端运行以下命令claude mcp add --transport http clickhouse-docs https://clickhouse.com/mcp --scope user网站现在会自动检测 Agent 发出的请求并向其返回 Markdown 而非 HTML 格式以便 Agent 能更快地处理内容同时消耗更少的 Token。更简洁的信息架构过去我们常收到反馈称文档难以导航因为顶部导航针对不同产品模块和用户目标设置了各种多级下拉菜单。在新版网站中我们简化了导航将开源版 ClickHouse 和 ClickHouse Cloud 共有的核心数据库功能文档与 Cloud 专属的产品文档分离开来。核心数据库文档现已根据不同的使用目标进行分类• Get started 此部分包含全新的快速启动导览、迁移指南、安装说明以及可供探索的示例数据集。• Concepts 此部分提供基础概念、核心产品功能概述和最佳实践帮助你充分利用 ClickHouse。• Guides 这里提供长篇内容帮助你达成特定目标或将 ClickHouse 应用于特定场景。• Reference 此部分提供关于函数、设置、数据类型、格式、表引擎等方面的参考文档。Cloud、ClickStack、Managed Postgres 等特定 ClickHouse 解决方案的文档现在统一放在“Solutions”标签页下并采用类似的分类结构。此外我们将集成文档拆分成了三个独立部分ClickPipes、语言客户端和连接器。围绕明确的用户目标来组织各产品模块的文档使我们能够为你提供更一致的阅读体验。API playground我们的 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?siZAIEQmVVAOlii257t596。期待你的反馈欢迎分享您对新网站的看法与反馈。您可以通过每个文档页面底部的反馈表单点赞或踩按钮以及“提交 Issue”按钮联系文档团队或者直接通过我们的 community slack 交流。您的反馈对我们打造更好的文档体验帮助极大https://clickhousedb.slack.com/join/shared_invite/zt-44wvsqbjb-53ggHzNoaCyG5k3dFDyOQA#/shared-invite/email。关于我们ClickHouse 是面向 AI 时代打造的高性能实时分析数据库能够以极致性能处理海量数据分析任务。凭借高并发、低延迟和云原生架构ClickHouse 广泛应用于可观测性、数据仓库、实时分析及 AI 数据基础设施等场景。我们致力于帮助企业在公有云平台上构建安全、弹性且高性价比的实时分析与 AI 数据平台加速释放数据价值推动智能化创新与数字化转型。目前Trip.com、DiDi、Meta、Sony、Netflix、Deutsche Bank、Sierra、Cloudflare 等全球领先企业均在使用 ClickHouse 支撑其关键业务和数据分析平台。