PostHog 文档体系全解docs/目录结构与发布流程实战指南【免费下载链接】posthog:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.项目地址: https://gitcode.com/GitHub_Trending/po/posthogPostHog 将开发者文档与代码同仓维护docs/README.md是这套体系的总入口定义了published/对外发布与internal/仓库内部两大目录的边界、发布流水线以及文档规范。本文将结合仓库中的 CI 工作流与校验脚本带你完整掌握 PostHog 文档的目录结构、发布流程、编写规范与自动化检查机制并给出可直接落地的实操建议。PostHog 文档体系代码与文档同 PR 演进PostHog 采用开发者文档紧跟代码的理念要求文档变更与代码变更放在同一个 PR 中提交。这一约定docs/README.md保证了文档与实现不会脱节任何行为变更都必须同步更新文档评审者可以在一个 PR 内同时审查代码与文档降低信息失真文档历史与代码历史完全对齐便于回溯排查。从仓库结构看docs/下有两个核心目录分别是面向外部用户的published/和仅存在于仓库内部的internal/两者共同构成 PostHog 的文档主干。目录结构published/与internal/的分工published/对外发布到 posthog.com 的文档published/目录下的文档在合并到 master 分支后会自动发布到 posthog.comURL 与目录结构一一对应——只需去掉docs/published/前缀即可docs/published/docs/surveys/... → posthog.com/docs/surveys/... docs/published/handbook/engineering/... → posthog.com/handbook/engineering/...实际示例published/docs/surveys/sdk-feature-support.md→/docs/surveys/sdk-feature-supportpublished/handbook/engineering/developing-locally.md→/handbook/engineering/developing-locally当前仓库中该目录包含的产品文档有docs/published/docs/business-knowledge/、data/、mcp-analytics/、surveys/等以及大量工程手册docs/published/handbook/engineering/例如 project-structure.md、developing-locally.md、stack.md 等。internal/仅存在于 GitHub 仓库的文档internal/存放只对团队有价值、不面向外部用户的知识例如开发工作流Development workflows迁移模式Migration patterns团队流程Team processesdocs/README.md特别强调PostHog 是开源的internal 只是指仅存在于 GitHub 仓库而非真正的私有内容。实际仓库中docs/internal/覆盖了非常多主题例如 monorepo-layout.md、dev-env-vars.md、django-startup-time.md、hogql-language-service.md、pgcollector.md 等并有feature-flags/、skills/、workflows/等子目录。使用原则对团队有用的知识放internal/用户产品文档与教程则放入 posthog.com 仓库。发布流程从 PR 到 posthog.com 的完整链路docs/README.md给出了发布流程的文字描述仓库中的 docs-preview-trigger.yml 工作流则提供了代码级的实现证据两者结合可以还原出完整链路Engineer creates PR with /docs/published/** changes ↓ GitHub Action triggers posthog.com preview build ↓ Preview URL posted to PR ↓ Merge to master ↓ Docs go live on posthog.com触发条件.github/workflows/docs-preview-trigger.yml 定义了工作流的触发路径on: pull_request: paths: - docs/** push: branches: - master paths: - docs/**即任何 PR 或 master 分支 push 中涉及docs/**的变更都会触发该工作流trunk-merge/开头的分支除外。三步自动化校验工作流内嵌了三道continue-on-error: true的检查不阻塞合并但会在 CI 报告中暴露问题Frontmatter 检查遍历docs/published/**/*.{md,mdx}用head -1确认每个文件以---开头缺失 YAML frontmatter 的文件会被标记。内部文档隔离检查在docs/published下查找文件名含internal、private、secret的文件防止内部文档误入公开目录。死链检查运行node .github/scripts/check-docs-links.js校验链接有效性。Vercel 预览构建校验通过后工作流调用 trigger-vercel-preview.sh 触发 posthog.com 的 Vercel 部署。该脚本的核心逻辑值得关注需要VERCEL_TOKEN、VERCEL_TEAM_ID、VERCEL_PROJECT_ID三个 secrets未配置时跳过通过 Vercel APIv13/deployments创建部署项目名为posthog-com关键机制构建环境变量GATSBY_POSTHOG_BRANCH被设置为当前 PR 分支名这样 Gatsby 构建时可以基于 monorepo 的 PR 分支内容生成预览部署成功后把deployment_url、deployment_id写入GITHUB_OUTPUT供后续步骤使用。预览链接回帖若事件类型是pull_request工作流会运行 post-docs-preview-section.mjs将预览部署地址回帖到 PR 的 CI 报告中。文档如何被 posthog.com 消费docs/README.md说明posthog.com 的 Gatsby 构建使用gatsby-source-git克隆本 monorepo并在构建过程中从/docs/published/拉取文件。也就是说monorepo 是 posthog.com 文档站的数据源而触发脚本中的GATSBY_POSTHOG_BRANCH正是为了让预览构建读取对应 PR 分支上的最新文档。文档编写规范docs/README.md明确了四条硬性规范所有发布文档必须带 YAML frontmatter——由 CI 脚本强制检查.github/workflows/docs-preview-trigger.yml。文档间使用相对链接例如../contributing/index.md。PostHog 内部知识如开发流程、迁移模式→ 放docs/internal/。用户产品文档与教程→ 放 posthog.com 仓库。一个实际范本可以参考 surveys/mcp.md——这是一篇标准的 published 文档内容涵盖通过 MCP 创建、启动、停止调查问卷的完整指南并包含参数表格如popover、widget、external_survey、api四种投放类型。链接检查机制深挖check-docs-links.js 的边界规则链接检查是文档质量的关键保障check-docs-links.js 实现了三条规则理解它能帮助写出不会触发 CI 报错的文档规则一相对链接必须可解析脚本用正则\[.*?\]\(([^)])\)提取所有 Markdown 链接然后忽略http(s)://、mailto:、/开头的绝对链接对相对链接按目标文件所在目录解析依次尝试精确文件、追加.md、追加.mdx、index.md、index.mdx五种候选published 文档存在边界约束链接解析结果不得逃出docs/published/目录否则报错escapes docs/published/ boundary。原因很直接——published 文档会被搬运到 posthog.com指向仓库其他位置的链接在线上必然 404。规则二指向本地文档的绝对链接应改为相对链接脚本会构建一个已发布 URL 索引将docs/published/下文件去掉.md/.mdx后缀、去掉/index后缀后得到 URL 路径集合凡是https://posthog.com/...形式的链接且 URL 路径命中该索引都会被标记为应使用相对链接。规则三posthog.com 绝对链接必须可访问对所有https://posthog.com/链接执行 HEAD 请求redirect: manual仅接受200/301/302/308状态码失败的链接会重试 3 次间隔 2 秒单请求超时 10 秒并以每批 10 个的并发度批量检查避免对目标服务器造成压力。实操指南在 PostHog 仓库中维护文档结合以上机制向本仓库贡献或修改文档时可遵循以下流程判断文档归属对外发布的产品/工程文档放docs/published/仅团队内部使用的工作流、迁移模式放docs/internal/。为 published 文档补齐 YAML frontmatter文件必须以---开头否则 CI frontmatter 检查会报错。链接规范published 文档只链接docs/published/内部的相对路径如../contributing/index.md风格不要使用指向本地文档的 posthog.com 绝对 URLinternal 文档可以链接仓库任意位置。与代码同 PR 提交按照 docs/README.md 的要求文档变更与代码变更放入同一 PR合并到 master 后文档即自动上线。善用 CI 反馈PR 创建后 docs-preview-trigger.yml 会自动执行三项检查并在 PR 中回帖预览地址可据此迭代修正。小结PostHog 的docs/目录是一个代码化的文档体系published/与internal/的边界划分保证了对外文档的纯净与内部知识的沉淀docs-preview-trigger.yml 与 check-docs-links.js 构成自动化的质量防线Gatsby Vercel 的链路则让文档变更可以像代码一样被预览、评审和上线。无论你是要为新功能补文档还是想理解 posthog.com 的内容供给机制本文梳理的目录结构、发布流程与校验规则都能作为直接的操作依据。【免费下载链接】posthog:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.项目地址: https://gitcode.com/GitHub_Trending/po/posthog创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考