This repository (mixpanel/docs) is the source for Mixpanel's public-facing documentation at docs.mixpanel.com. It serves as both a documentation platform and a comprehensive reference for Mixpanel's analytics product, covering SDKs, APIs, data governance, and analytics features.
The repository fulfills two primary functions:
[email protected] with [email protected], deployed to Vercel@redocly/[email protected] and published to developer.mixpanel.comThe platform processes approximately 500+ MDX documentation pages and 10+ OpenAPI specification files, covering the complete Mixpanel product ecosystem including client SDKs (JavaScript, iOS, Android), server SDKs (Python, Node.js, Java), warehouse integrations, and analytics APIs.
The repository is organized into distinct subsystems, each documented in dedicated wiki sections:
Core Application Layer
Content Source to Output Mapping
Navigation to Detailed Documentation:
Sources: package.json1-60 README.md1-100 openapi/openapi.config.yaml1-48 pages/_app.tsx1-100 theme.config.tsx1-200 middleware.ts1-16
The documentation platform is built on modern web technologies with strict version constraints:
| Component | Version | Purpose | Config File |
|---|---|---|---|
next | 14.2.32 | React framework, static site generation | next.config.mjs |
nextra | 3.3.1 | Documentation framework with MDX support | theme.config.tsx |
nextra-theme-docs | 3.3.1 | Pre-built documentation theme | theme.config.tsx |
@redocly/cli | 1.34.5 | OpenAPI validation and bundling | openapi/openapi.config.yaml |
cspell | 9.2.1 | Spell checking automation | cspell.json |
@sentry/react | 8.50.0 | Error tracking and monitoring | pages/_app.tsx |
@docsearch/react | 3.9.0 | Algolia search integration | components/Search/ |
sass | 1.92.1 | SCSS stylesheet compilation | pages/overrides.scss |
typescript | 5.9.3 | Type safety for components | tsconfig.json |
next-sitemap | 4.2.3 | Sitemap generation | next-sitemap.config.js |
Runtime Requirements:
>=20.0.0 <21.0.0>=10.0.0 <12.0.0Sources: package.json27-58 package-lock.json1-100
Directory Organization and Key Files
mixpanel/docs/
├── pages/ # Next.js pages and routing
│ ├── docs/ # Product documentation (500+ MDX files)
│ │ ├── _meta.tsx # Navigation structure configuration
│ │ ├── tracking/ # SDK implementation guides
│ │ ├── data-structure/ # Data model documentation
│ │ ├── features/ # Product feature docs
│ │ └── privacy/ # Privacy and compliance
│ ├── changelogs/ # Product update announcements
│ │ ├── _meta.tsx # Changelog navigation
│ │ └── *.mdx # Individual changelog posts
│ ├── guides/ # Tutorial content
│ ├── _app.tsx # Application wrapper (GTM, Mixpanel, Sentry)
│ ├── _document.js # HTML document structure
│ └── overrides.scss # Global theme styling (1500+ lines)
├── openapi/ # API documentation system
│ ├── src/ # OpenAPI YAML specifications
│ │ ├── ingestion.openapi.yaml # /track, /engage, /groups APIs
│ │ ├── query.openapi.yaml # Reports API
│ │ ├── export.openapi.yaml # Raw data export API
│ │ ├── data-pipelines.openapi.yaml
│ │ ├── lexicon-schemas.openapi.yaml
│ │ ├── feature-flags.openapi.yaml
│ │ ├── gdpr.openapi.yaml
│ │ └── common/ # Shared schemas and auth
│ ├── out/ # Bundled JSON output
│ ├── openapi.config.yaml # Redocly bundling config
│ └── publish.js # ReadMe publishing script
├── reference/ # API reference markdown pages
│ └── Mixpanel APIs/
│ └── overview.md
├── components/ # React components
│ ├── FeedbackCollector/ # User feedback widget
│ ├── Search/ # Custom search UI
│ └── ChangelogIndex.tsx # Changelog listing
├── redirects/ # URL redirect mappings
│ ├── local.txt # Internal redirects
│ ├── help-mixpanel-com.txt # Legacy help.mixpanel.com → docs.mixpanel.com
│ └── developer-mixpanel-com.txt # Legacy developer.mixpanel.com redirects
├── public/ # Static assets
│ ├── changelog/ # Changelog images and videos
│ └── *.png # Documentation screenshots
├── theme.config.tsx # Nextra theme configuration
├── next.config.mjs # Next.js build config, redirects
├── middleware.ts # Security headers, CSP
├── package.json # Dependencies and npm scripts
├── cspell.json # Spell checker configuration
└── README.md # Contributor guidelines
Key Configuration Files:
| File | Purpose | Key Sections |
|---|---|---|
theme.config.tsx | Nextra theme configuration | Logo, navigation, search, footer, social links |
next.config.mjs | Next.js build settings | Redirects (1000+ rules), image domains, output config |
middleware.ts | Request middleware | Content-Security-Policy, security headers |
openapi/openapi.config.yaml | API bundling configuration | 10+ API specs, output paths, linting rules |
pages/_app.tsx | Application initialization | GTM, Mixpanel tracking, Sentry, Sprig, Kapa AI |
cspell.json | Spell checking settings | Custom dictionary, ignored patterns |
Sources: README.md60-75 package.json1-60 openapi/openapi.config.yaml1-48
Build Process Architecture
npm Scripts and Their Functions
| Command | Script (from package.json) | Purpose | Primary Files |
|---|---|---|---|
npm run dev | next dev | Start development server with hot reload | next.config.mjs, pages/_app.tsx |
npm run build | next build | Generate production static site | next.config.mjs, theme.config.tsx |
npm run postbuild | next-sitemap | Generate sitemap after build | next-sitemap.config.js |
npm run start | next start | Serve production build locally | .next/ output |
npm run spelling | cspell '**/*.md*' | Validate spelling across MDX files | cspell.json |
npm run api:build | redocly bundle --config=./openapi/openapi.config.yaml | Bundle OpenAPI YAML to JSON | openapi/src/*.yaml → openapi/out/*.json |
npm run api:lint | openapi --config=./openapi/openapi.config.yaml --format=stylish lint | Validate OpenAPI specifications | openapi/openapi.config.yaml |
npm run api:publish | node ./openapi/publish.js | Publish API docs to ReadMe | openapi/publish.js, rdme CLI |
npm run api:test | ./openapi/test.sh | Run API specification tests | openapi/test.sh |
npm test | ./utils/test.sh | Run complete test suite | utils/test.sh |
GitHub Actions CI/CD Workflows
Deployment Workflow:
docs-git-branch-mixpanel.vercel.app) + ReadMe staging branch (3.27-pr-XXX)docs.mixpanel.com within 1-2 minutes + ReadMe v3.27 branch updaterdme-delete-staging.ymlSources: package.json5-16 README.md27-74 openapi/openapi.config.yaml1-48
Content Flow Through Build System
Content Type Documentation Map:
| Content Type | Source Location | Processing | Output Destination | Wiki Section |
|---|---|---|---|---|
| Product Docs | pages/docs/**/*.mdx | Nextra MDX processor | docs.mixpanel.com/docs/* | Section 4 |
| Changelogs | pages/changelogs/*.mdx | Nextra MDX processor | docs.mixpanel.com/changelogs/* | Section 2.3 |
| Guides | pages/guides/**/*.mdx | Nextra MDX processor | docs.mixpanel.com/guides/* | Section 4 |
| API Reference | openapi/src/*.yaml | Redocly bundler | developer.mixpanel.com | Section 3 |
| Static Assets | public/**/* | Next.js static file handling | CDN | Section 2.3 |
| Redirects | redirects/*.txt | Next.js middleware | HTTP 301/302 responses | Section 2.3 |
Supported API Specifications:
| Specification File | API Category | Output Bundle |
|---|---|---|
ingestion.openapi.yaml | Event tracking, profile updates | ingestion-api.json |
query.openapi.yaml | Reports and analytics queries | query-api.json |
export.openapi.yaml | Raw data export | event-export-api.json |
data-pipelines.openapi.yaml | Warehouse export configuration | data-pipelines-api.json |
lexicon-schemas.openapi.yaml | Data dictionary management | lexicon-schemas-api.json |
feature-flags.openapi.yaml | Feature flag evaluation | feature-flags-api.json |
gdpr.openapi.yaml | Data privacy compliance | gdpr-api-2.json |
Sources: openapi/openapi.config.yaml1-48 package.json5-16 next.config.mjs1-50
External Services Architecture
Integration Configuration Locations:
| Service | Configuration File | Purpose | Implementation Details |
|---|---|---|---|
| Google Tag Manager | pages/_app.tsx | Page view tracking, conversion events | GTM container ID: GTM-KV3FC2C |
| Mixpanel | pages/_app.tsx | Product analytics, dogfooding | Track page views, clicks, search queries |
| Sentry | pages/_app.tsx | Error monitoring, performance | DSN configured, release tracking enabled |
| Sprig | pages/_app.tsx | User surveys, feedback collection | Conditional loading based on environment |
| Kapa AI | theme.config.tsx | AI-powered search widget | Custom chat interface integration |
| Algolia DocSearch | theme.config.tsx | Documentation search | Index ID: mixpanel-docs |
| Intercom | theme.config.tsx | Live support chat | Conditional display for logged-in users |
| Content Security Policy | middleware.ts | Security headers | Defines allowed domains for scripts, images, frames |
Environment-Specific Loading:
Services are conditionally loaded based on NODE_ENV and custom feature flags to prevent tracking during development:
NODE_ENV=development): Analytics disabled, local-only featuresdocs.mixpanel.com): All integrations active, full tracking enabledSources: pages/_app.tsx1-100 theme.config.tsx1-200 middleware.ts1-16
This repository documents the complete Mixpanel product ecosystem across multiple product areas:
Product Documentation Organization:
| Product Area | Documentation Scope | Wiki Section | Primary File Locations |
|---|---|---|---|
| API Documentation | 11 OpenAPI specs for Ingestion, Query, Export, Feature Flags, GDPR, Lexicon, Data Pipelines, Warehouse Connectors | Section 3 (API System) Section 4 (API Reference) | openapi/src/*.openapi.yamlreference/Mixpanel APIs/*.md |
| Client SDKs | JavaScript SDK, iOS, Android, React Native, Flutter | Section 5.1 (JavaScript SDK) Section 5.5 (Mobile SDKs) | pages/docs/tracking/pages/docs/tracking/mobile/ |
| Session Replay | Web replay (rrweb), mobile replay (pixel capture), privacy controls | Section 5.2 | pages/docs/session-replay/ |
| Heatmaps & Click Analytics | Heatmap integration, rage click, dead click detection | Section 5.3 | pages/docs/heatmaps/ |
| Traffic Attribution | UTM tracking, referrer capture, mobile attribution | Section 5.4 | pages/docs/tracking/attribution/ |
| Data Model | Events, user profiles, group profiles, lookup tables | Section 6.1 | pages/docs/data-structure/ |
| Warehouse Connectors | BigQuery, Snowflake, Databricks, Redshift, Postgres import | Section 6.2 | pages/docs/data-pipelines/warehouse-connectors/ |
| Data Pipelines | JSON Pipelines, incremental exports, identity mappings | Section 6.3 | pages/docs/data-pipelines/export/ |
| Hot Shard Management | Detection, thresholds, transformation, remediation | Section 6.4 | pages/docs/data-structure/hot-shards/ |
| Pricing & Billing | Free, Growth, Enterprise plans, MTU billing, Startup Program | Section 7 | pages/docs/pricing/ |
API Specifications by File
OpenAPI Specification Details:
| Specification File | x-readme-deploy-id | Primary Endpoints | Output Bundle |
|---|---|---|---|
ingestion.openapi.yaml | ingestion | /track, /engage, /groups, /import | ingestion-api.json |
identity.openapi.yaml | identity | /track#create-identity, $merge, $create_alias | identity-api.json |
feature-flags.openapi.yaml | feature-flags-api | /flags, /flags/definitions | feature-flags-api.json |
query.openapi.yaml | query | Reports, insights, funnels, retention | query-api.json |
export.openapi.yaml | export | /export raw data download | event-export-api.json |
data-pipelines.openapi.yaml | data-pipelines | Warehouse export configuration | data-pipelines-api.json |
lexicon-schemas.openapi.yaml | lexicon-schemas | Data dictionary CRUD operations | lexicon-schemas-api.json |
gdpr.openapi.yaml | gdpr | Data retrieval, deletion requests | gdpr-api-2.json |
warehouse-connectors.openapi.yaml | warehouse-connectors | Manual import trigger | warehouse-connectors-api.json |
service-accounts.openapi.yaml | service-accounts | Service account management | service-accounts-api.json |
annotations.openapi.yaml | annotations | Event annotation CRUD | annotations-api.json |
Sources: openapi/openapi.config.yaml1-48 openapi/src/ingestion.openapi.yaml1-50 openapi/src/identity.openapi.yaml1-50 openapi/src/feature-flags.openapi.yaml1-50 reference/Mixpanel APIs/overview.md1-73
The system implements comprehensive security policies through Next.js middleware:
The middleware configuration in middleware.ts3-16 sets comprehensive Content Security Policy headers that restrict resource loading to approved domains while allowing necessary third-party integrations for analytics, support, and media embedding.
Sources: middleware.ts1-16
Refresh this wiki
This wiki was recently refreshed. Please wait 7 days to refresh again.
