posthog/docs

PostHog Documentation

Developer-focused documentation alongside code. Update existing docs in the same PR as your code changes. Add a new doc only when a person asks for it.

Structure

published/ - Published on posthog.com

Documentation published when merged to master. The URL mirrors the directory structure - just strip the docs/published/ prefix:

docs/published/docs/surveys/...          →  posthog.com/docs/surveys/...
docs/published/handbook/engineering/...  →  posthog.com/handbook/engineering/...

Examples:

• published/docs/surveys/sdk-feature-support.md → /docs/surveys/sdk-feature-support
• published/handbook/engineering/developing-locally.md → /handbook/engineering/developing-locally

internal/ - GitHub-only

Documentation that stays in the repository:

• Development workflows
• Migration patterns
• Team processes

When to use: Knowledge useful for the team but not for external users. We're open source, so "internal" means GitHub-only rather than truly private.

Publishing Flow

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

The posthog.com Gatsby build uses gatsby-source-git to clone this monorepo and pull files from /docs/published/ during the build process.

Guidelines

• All published docs must have YAML frontmatter
• Use relative links between docs: ../contributing/index.md
• Docs about PostHog internals → here
• User product docs and tutorials → posthog.com repo

Setup

For posthog.com team setting up the integration, see the PRs in PostHog/posthog.com repo.