Kaneo 文档站搭建指南：基于 Mintlify 的 Monorepo 文档架构与本地预览

Kaneo 文档站搭建指南基于 Mintlify 的 Monorepo 文档架构与本地预览【免费下载链接】app All you need. Nothing you dont. Open source project management that works for you, not against you.项目地址: https://gitcode.com/GitHub_Trending/app116/appKaneo/kəˈneɪ.oʊ/是一个强调「All you need. Nothing you dont.」的开源项目管理工具其官方文档站点位于仓库的apps/docs目录由 Mintlify 驱动。本文以 apps/docs/README.md 为主线完整讲解该文档站如何在 monorepo 中组织、如何通过docs.json配置导航与主题、如何基于本地 OpenAPI 文件自动生成 API 参考页以及如何在本地启动mint dev进行实时预览帮助你在自托管 Kaneo 时快速搭建与维护属于自己的文档站点。一、文档站与 Kaneo 的整体关系Kaneo 的文档站不是独立仓库而是作为 pnpm monorepo 中的一个 workspace 存在。从根目录的 pnpm-workspace.yaml 可以看到仓库同时收纳了packages/**与apps/**两类 workspaceapps/api基于 Hono TypeScript 构建的后端 APIapps/web基于 React Tailwind CSS 构建的前端 Web 应用apps/docs本文主角Mintlify 驱动的文档站apps/siteKaneo 的营销站点Next.jspackages/*email、mcp、permissions、planka-import、libs 等共享包。其中apps/docs承担了「面向用户和开发者的一切说明」产品使用指南、安装部署指南、集成配置、社交登录、迁移以及自动生成的 API 参考。README 中明确给出了该目录的四个关键定位仓库名kaneoMintlify 文档根目录apps/docs主配置apps/docs/docs.jsonOpenAPI 源文件apps/docs/openapi.json二、目录结构内容、API 参考与配置的分层apps/docs内部采用「内容目录 API 参考 全局配置」的分层结构路径作用index.mdx文档站点落地页即「Why Kaneo」首页core/**产品使用与部署指南functional、installation、integrations、social-providers、deployments、migrations、reverse-proxyapi-reference/**API 概览与鉴权说明端点页面由 OpenAPI 文件自动生成docs.jsonMintlify 的全局配置导航、主题、Logo、SEO、统计集成等openapi.json从 API 源码导出的 OpenAPI 规范是 API 参考页的数据源以 apps/docs/api-reference/introduction.mdx 为例其首页明确说明「Kaneo API endpoint pages are generated automatically from our OpenAPI specification」并给出了 API 的 Base URL 约定https://your-kaneo-instance.com/api也就是说api-reference/endpoints/**下的端点页面不是手写的而是由 Mintlify 读取openapi.json后自动渲染的这保证了文档与代码始终同源。三、docs.json导航、主题与站点的总控apps/docs/docs.json 是整个文档站的核心配置值得逐项拆解3.1 主题与外观{ theme: almond, colors: { primary: #111111, light: #fafafa, dark: #1f1f1f }, appearance: { default: dark }, fonts: { family: Geist Variable, source: /fonts/geist.woff2, format: woff2 }, favicon: /favicon.svg, logo: { light: /logo/dark.svg, dark: /logo/light.svg } }appearance.default: dark表示站点默认以暗色主题呈现字体使用 Geist Variablewoff2 文件位于仓库的 apps/docs/fonts/geist.woff2明暗两套 Logo 分别对应 apps/docs/logo/dark.svg 与 apps/docs/logo/light.svg代码块明暗主题分别采用min-light与min-dark代码块在暗色主题下默认使用min-dark配色保证阅读体验一致。3.2 导航navigation导航分为两个 TabGuides包含 Overview、Functional Guides、Installation、GitHub/Gitea Integration、IntegrationsMCP、Discord、Slack、Telegram、Outgoing Webhooks、Authentication Providers、Deployment Operations、Migration 等分组每一组都按顺序列出对应.mdx页面API Reference通过openapi: openapi.json直接挂载 OpenAPI 规范Mintlify 据此自动生成全部端点页面。全局锚点global.anchors在导航栏固定提供 Website 与 GitHub 两个入口navbar.links中的 GitHub 链接和Open Kaneo主按钮则构成了顶栏的常驻操作。3.3 上下文操作、SEO 与统计contextual: { options: [copy, view, chatgpt, claude, cursor] }contextual.options启用了文档正文的「复制、查看」以及一键发送给 ChatGPT / Claude / Cursor 的上下文操作方便读者把文档内容直接带入 AI 工具——这也是让文档更容易被 Agent 检索与引用的关键配置。SEO 部分配置了og:site_name、og:type、twitter:card等元标签并接入 Plausible 统计integrations: { plausible: { domain: kaneo.app, server: plausible.kaneo.app } }此外还定义了一条重定向规则/core/guide/migrating-from-v1被重定向到/core/installation/environment-variables保证旧版本链接不失效。四、OpenAPI 自动生成从 API 源码到 docs/openapi.jsonREADME 提到「API endpoints are generated from the local OpenAPI file indocs.json」那么openapi.json从哪来答案是仓库内的导出脚本 apps/api/scripts/export-openapi.tsimport { writeFile } from node:fs/promises; import { resolve } from node:path; import { createApp } from ../src/index; process.env.KANEO_API_URL https://cloud.kaneo.app; const { app } createApp(); const response await app.request(/api/openapi); const spec await response.json(); const outputPath process.argv[2] ? resolve(process.argv[2]) : resolve(import.meta.dirname, ../../docs/openapi.json); await writeFile(outputPath, ${JSON.stringify(spec, null, 2)}\n);从源码可以看出整条链路createApp()创建 Hono 应用定义于 apps/api/src/index.ts请求GET /api/openapi获取运行时生成的 OpenAPI 规范对应 apps/api/src/openapi.ts 的 openapi 路由默认输出到apps/docs/openapi.json也可以传入命令行参数自定义输出路径。也就是说每当你修改 API 路由或 Schema重新运行该导出脚本apps/docs/openapi.json就会与最新接口保持同步mint dev预览的 API 参考页也随之更新。这就是「文档与代码同源」的完整闭环。五、本地预览安装 mint 并启动 dev serverREADME 给出的本地预览流程非常简洁共三步第 1 步全局安装 Mintlify CLInpm i -g mint第 2 步在 docs 目录下启动开发服务器mint dev注意命令必须从apps/docs目录运行因为 Mintlify 会以当前目录下的docs.json作为配置入口。第 3 步打开预览http://localhost:3000mint dev提供热更新编辑core/**下的任意.mdx页面、调整docs.json的导航分组或者更新openapi.json浏览器都会即时反映变更非常适合在提交文档前快速校对链接与排版。六、内容结构从落地页到功能指南6.1 落地页Why Kaneoapps/docs/index.mdx 是文档站首页开篇点明项目定位——「project management that stays out of your way」并给出四条快速入口Quick Startapps/docs/core/index.mdx最快路径跑起一个实例Installation Guide在 drim 与 Docker Compose 之间做选择GitHub / Gitea 集成配置用于仓库同步Outgoing webhooksSlack、Discord 与自定义 HTTP 通知API Introduction鉴权后的 API 使用。落地页还阐述了 Kaneo 的产品理念与轻量规划方式用 Labels 表示onboarding、backend、customer-feedback等工作流将标签与优先级、截止日期组合实现更清晰的规划并在工作区内保持命名一致以保证筛选有效。6.2 功能与部署指南core/**覆盖了从安装到日常运维的完整路径core/functional/**创建工作区与项目、规划与执行任务、backlog 规划、团队协作、工作流配置、账户通知、个性化工作区、标签管理等core/installation/**drim、drim 迁移、Docker Compose、对象存储与图片上传、环境变量、启动服务core/integrations/**GitHub / Gitea / MCP / Discord / Slack / Telegram / 出站 Webhookcore/social-providers/**GitHub、Google、Discord 与自定义 OAuthcore/deployments/**Railway 与 Coolify 部署core/migrations/**从 PLANKA 迁移。以 Quick Start 页 apps/docs/core/index.mdx 为例它把安装方式浓缩为两条命令curl -fsSL https://assets.kaneo.app/install.sh | sh drim setup若需要更多控制力则依次阅读 Docker Compose、环境变量、启动服务三篇指南。这种「一条推荐路径 手动路径」的组织方式贯穿整个core/**让新手与运维老手各取所需。6.3 API 参考鉴权与端点apps/docs/api-reference/authentication.mdx 详细说明了两种 API 鉴权方式API Key适用于脚本、服务与长期集成的稳定凭据。创建后通过Authorization: Bearer key请求头使用且密钥只在创建时展示一次必须立即保存Device AuthorizationRFC 8628适用于 CLI、桌面应用等需要浏览器授权的场景。流程为请求/api/auth/device/code获取device_code与user_code→ 用户在浏览器中打开验证链接并批准 → 客户端轮询/api/auth/device/token换取 Bearer token。设备授权流程与仓库中 MCP 客户端的实现直接相关自托管实例默认只允许kaneo-cli与kaneo-mcp两个设备客户端 ID若要用自定义client_id实例管理员必须通过DEVICE_AUTH_CLIENT_IDS环境变量显式放行。对应的测试用例可参考 tests/api/mcp-oauth-security.test.ts 与 tests/api-integration/mcp-oauth-store.test.ts。该页同时给出了安全最佳实践密钥不入库、命名清晰、定期轮换、限制信任范围、定期审查、仅放行可信设备客户端 ID、把设备 Bearer token 当作密钥对待。七、与 Monorepo 构建体系的协同文档站虽然不参与构建产物但它与仓库的 Turbo 构建任务共享同一套 workspace 约定。根目录 turbo.json 定义了build、dev、lint、typecheck、test、test:integration等任务其中dev任务persistent: true意味着可以在开发模式下常驻运行——mint dev正是以同样的常驻方式服务文档预览。而apps/docs/openapi.json的更新依赖apps/api的运行时导出脚本因此对文档维护者而言一条典型的更新路径是修改 API 路由或 Schemaapps/api/src运行 apps/api/scripts/export-openapi.ts 重新生成apps/docs/openapi.json在apps/docs下执行mint dev校验 API 参考页渲染效果。八、总结apps/docs是 Kaneo 文档体系的中枢以 apps/docs/docs.json 为配置入口core/**承载人工撰写的使用与部署指南openapi.json驱动 API 参考自动生成index.mdx作为落地页聚合所有入口。借助 Mintlify CLI一条npm i -g mint mint dev即可在http://localhost:3000获得实时预览。对于希望自托管并二次开发 Kaneo 的团队理解这套文档架构意味着可以低成本地把产品能力、部署方式和 API 契约完整、持续地呈现给用户与 AI 工具。【免费下载链接】app All you need. Nothing you dont. Open source project management that works for you, not against you.项目地址: https://gitcode.com/GitHub_Trending/app116/app创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考