How github/docs works
Project type and purpose
• This is a full-stack documentation website (docs.github.com) built with Next.js (React + Node/TypeScript).
• It ingests Markdown content (in content/, data/ and assets/), transforms it via content-render, content-linter, and other pipelines, then serves it through a Next.js server with dynamic API routes (article-api, REST, GraphQL, search, audit-logs, secret-scanning, webhooks, etc.).
• CI/CD is orchestrated by GitHub Actions, and production runs in Docker/Kubernetes behind a CDN (Fastly).
Main components
a. Source content & data
• content/, data/, assets/: Markdown, YAML, CSV source files
• data-directory, automated-pipelines, ghes-releases, etc.: scripts to validate/generate derived JSON/HTML
b. Build & CI/CD
• .github/workflows: lint, test, build, deploy pipelines
• Dockerfile + docker-compose + .devcontainer: containerize for local dev and staging/prod
c. Core application
• Next.js frontend (src/frame + src/pages): React pages and dynamic route handlers
• API routes (under src/*-api, src/rest, src/graphql, src/search, etc.): serverless/Express-style functions
• Shared libraries (src/content-render, src/content-linter, src/assets, src/data-directory)
d. Infrastructure & deployment
• config/kubernetes: manifests for webapp Deployment + Service
• config/moda: feature-flag & environment configs
• External services: Elasticsearch cluster for site search; Fastly for CDN & remote JSON caching; optional S3/minio for assets
e. Tests & monitoring
• src/tests, fixtures, vitest.config.ts: unit, integration, e2e (Playwright)
• observability: StatsD, error handling, failbot
• workflows: slack alerts, dead link checks
Component interactions
• Developer → GitHub → GitHub Actions (CI): runs content-linter, tests, builds artifacts → pushes Docker image
• Kubernetes (Production & Staging): pulls image → runs Next.js server + API routes
• CDN (Fastly) sits in front of the Next.js origin, caching both pages and remote JSON endpoints
• Next.js server’s API routes query:
• local JSON (generated under public or via remotejson) for content, data, assets
• Elasticsearch for general and AI search
• static JSON schemas for REST/GraphQL docs
• Client browsers fetch pages + assets via CDN; JS hydration for interactive features
Architectural patterns & principles
• Monorepo with clear separation of concerns: content, data pipelines, services, frontend
• “Headless CMS” approach: Markdown + JSON → API → page rendering
• Next.js Server-Side Rendering + Dynamic Routes for versioned docs
• Feature-flag driven code (config/moda, useFeatureFlags hook)
• Microservices-within-Next.js: each subfolder under src/*-api or src/* acts as its own API endpoint
• Kubernetes + GitOps for deployments