This document provides an introduction to the Mixpanel documentation repository, which generates the official documentation site at https://docs.mixpanel.com. This repository combines content documentation (written in MDX), OpenAPI-based API reference documentation, and supporting interactive components into a unified static site built on Nextra 3.0 and Next.js.
For detailed information about specific subsystems:
The Mixpanel documentation repository at github.com/mixpanel/docs is a monorepo that produces the static documentation site deployed at docs.mixpanel.com.
mixpanel/docs/
├── pages/ # MDX content files (Nextra convention)
│ ├── docs/ # Product documentation
│ ├── changelogs/ # Product update announcements
│ └── _meta.tsx # Navigation configuration
├── openapi/ # API documentation system
│ ├── src/ # Source OpenAPI YAML specs (11 files)
│ ├── out/ # Bundled JSON output (generated)
│ └── openapi.config.yaml # Redocly bundler configuration
├── public/ # Static assets (images, diagrams)
├── reference/ # Generated API reference pages
├── redirects/ # Legacy URL redirect rules (500+)
│ ├── local.txt
│ ├── help-mixpanel-com.txt
│ └── developer-mixpanel-com.txt
├── theme.config.tsx # Nextra theme configuration
├── next.config.mjs # Next.js build configuration
├── cspell.json # Spell checker configuration
└── package.json # Dependencies and build scripts
Sources: README.md1-100 package.json1-60 openapi/openapi.config.yaml1-48
The documentation site is built on the following core technologies:
| Technology | Version | Purpose |
|---|---|---|
| Next.js | 14.2.32 | Static site generation framework |
| Nextra | 3.3.1 | Documentation theme and framework |
| nextra-theme-docs | 3.3.1 | Pre-built documentation theme components |
| React | 18.3.1 | UI component library |
| Redocly CLI | 1.34.5 | OpenAPI bundling and validation |
| TypeScript | 5.9.3 | Type-safe configuration and components |
| CSpell | 9.2.1 | Automated spell checking |
| Sass | 1.92.1 | CSS preprocessing for theme customization |
Node.js Requirements: Node.js >=20.0.0 <21.0.0, npm >=10.0.0 <12.0.0
Sources: package.json27-58
Sources: package.json5-15 openapi/openapi.config.yaml1-48 README.md28-40
Sources: package.json5-15 openapi/openapi.config.yaml1-48 README.md28-58
Sources: package.json5-15
The repository maintains 11 OpenAPI 3.0 specifications in openapi/src/ that define Mixpanel's public APIs:
| Source Specification | Bundled Output | Config Key | Purpose |
|---|---|---|---|
src/ingestion.openapi.yaml | out/ingestion-api.json | ingestion | Event tracking and profile updates |
src/identity.openapi.yaml | out/identity-api.json | identity | User identity management |
src/feature-flags.openapi.yaml | out/feature-flags-api.json | featureflags | Feature flag evaluation |
src/query.openapi.yaml | out/query-api.json | query | Report queries and analytics |
src/export.openapi.yaml | out/event-export-api.json | export | Raw data export |
src/data-pipelines.openapi.yaml | out/data-pipelines-api.json | data-pipelines | Warehouse exports |
src/gdpr.openapi.yaml | out/gdpr-api-2.json | gdpr | GDPR compliance endpoints |
src/lexicon-schemas.openapi.yaml | out/lexicon-schemas-api.json | lexicon-schemas | Data schema management |
src/warehouse-connectors.openapi.yaml | out/warehouse-connectors-api.json | warehouse-connectors | Warehouse import triggers |
src/service-accounts.openapi.yaml | out/service-accounts-api.json | service-accounts | Service account management |
src/annotations.openapi.yaml | out/annotations-api.json | annotations | Report annotations |
The npm run api:build script executes:
This processes each API specification defined in openapi/openapi.config.yaml1-35 resolving all $ref references and combining shared components from openapi/src/common/ (including securitySchemes.yaml, responses.yaml, and regional server configurations).
Sources: openapi/openapi.config.yaml1-48 package.json6
Content is organized in the pages/ directory using MDX (Markdown with JSX). The Nextra framework automatically generates routes from the file structure:
pages/
├── index.mdx # Homepage
├── docs/ # Main documentation
│ ├── _meta.tsx # Navigation configuration
│ ├── quickstart/ # Getting started guides
│ ├── tracking-methods/ # SDK documentation (14 platforms)
│ ├── data-structure/ # Events, profiles, groups, lookup tables
│ ├── reports/ # Analytics reports
│ ├── features/ # Feature flags, session replay
│ ├── data-pipelines/ # Warehouse connectors & exports
│ ├── orgs-and-projects/ # Administration
│ └── pricing/ # Billing documentation
├── changelogs/ # Product announcements
│ ├── _meta.tsx
│ └── YYYY-MM-DD-*.mdx # Changelog entries with frontmatter
└── reference/ # Generated API reference pages
Navigation is defined via _meta.tsx or _meta.ts files in each directory. These replaced Nextra 2.0's _meta.json format and support:
Example structure in pages/docs/_meta.tsx:
Sources: README.md12-26 README.md76-78
The site uses nextra-theme-docs@3.3.1 configured in theme.config.tsx
| Package | Version | Purpose |
|---|---|---|
nextra | 3.3.1 | Core documentation framework |
nextra-theme-docs | 3.3.1 | Pre-built theme components |
@docsearch/react | 3.9.0 | Algolia search UI |
@docsearch/js | 3.9.0 | Algolia search integration |
sass | 1.92.1 | SCSS preprocessing |
@headlessui/react | 2.2.9 | Accessible UI components |
@sentry/react | 8.50.0 | Error tracking |
Located throughout the codebase:
FeedbackCollector: User feedback widgetChangelogPostHeader: Standardized changelog formattingVideoButtonWithModal: Embedded video playertailwindcss@3.4.14 and autoprefixer@10.4.21Sources: package.json31-44 README.md76-78
The repository maintains 623+ redirect rules (as indicated in the high-level diagrams) across three files to preserve legacy URLs and handle content reorganization:
| Redirect File | Source Domain | Purpose |
|---|---|---|
redirects/local.txt | docs.mixpanel.com | Internal restructuring (288 redirects) |
redirects/help-mixpanel-com.txt | help.mixpanel.com | Legacy help site migration (269 redirects) |
redirects/developer-mixpanel-com.txt | developer.mixpanel.com | Legacy developer site migration (66 redirects) |
These rules are processed during the Next.js build (configured in next.config.mjs) and ensure backward compatibility with old documentation URLs. The redirect system prevents broken links from external sites and search engines.
Sources: High-level system diagrams, README.md12-26
The development server supports hot module reloading for both MDX content and React components. OpenAPI changes require running api:build to regenerate JSON bundles.
Sources: README.md28-58
The production build follows this sequence:
npm run api:build to bundle OpenAPI specificationsnpm run build to generate static Next.js sitenext-sitemap via the postbuild script.next/ directoryThe build generates fully static HTML pages with client-side hydration for interactive components.
Sources: package.json10-11
All pull requests generate staging links in Vercel for preview. Once merged to the main branch, changes automatically deploy to production within 1-2 minutes.
Sources: README.md70-75 README.md86-93
Product updates are documented in `pages/changelogs/` as MDX files with frontmatter:
The ChangelogPostHeader component renders changelog posts with consistent formatting. All changelog posts must include either a video (Loom link) or thumbnail (preview image) in the frontmatter.
Sources: README.md80-84 pages/changelogs/2024-05-09-home.mdx1-29 pages/changelogs/2024-05-09-column-charts.mdx1-31
The repository uses CSpell for automated spell checking:
Configuration is managed in `cspell.json` The VSCode extension streetsidesoftware.code-spell-checker is recommended for real-time spell checking during development.
Sources: README.md42-58
OpenAPI specifications are validated during the build:
This command uses Redocly CLI with rules defined in `openapi/openapi.config.yaml` to ensure API documentation quality.
Sources: package.json7 openapi/openapi.config.yaml36-48
The repository accepts contributions via GitHub pull requests:
For multiple related changes, contributors should commit to the same branch before creating a pull request to consolidate edits.
Sources: README.md14-26 README.md86-93
Mixpanel supports three regional deployments for data residency compliance. OpenAPI specifications define regional variations using server variables in the servers section.
| Region | Ingestion API | Query API | Export API | Feature Flags API |
|---|---|---|---|---|
| US (Default) | api.mixpanel.com | mixpanel.com/api | data.mixpanel.com/api/2.0/export | api.mixpanel.com/flags |
| EU Residency | api-eu.mixpanel.com | eu.mixpanel.com/api | data-eu.mixpanel.com/api/2.0/export | api-eu.mixpanel.com/flags |
| India Residency | api-in.mixpanel.com | in.mixpanel.com/api | data-in.mixpanel.com/api/2.0/export | api-in.mixpanel.com/flags |
From openapi/src/common/feature-flags-api.yaml1-16:
This pattern is consistent across all API specifications in openapi/src/common/
Sources: openapi/src/common/feature-flags-api.yaml1-16 reference/Mixpanel APIs/overview.md14-73
The site organizes content into six primary categories with custom icons:
Each category's navigation is defined in its respective _meta.tsx file using Nextra 3.0's TypeScript-based metadata system.
Sources: README.md76-78
Refresh this wiki
This wiki was recently refreshed. Please wait 1 day to refresh again.
