How jetbrains/kotlin-web-site works
Project Type and Purpose
• This is the source code for the Kotlin website (kotlinlang.org).
• It is a full-stack, largely static website generator combining:
• A Node/Next.js/React-based frontend for interactive pages and static generation
• A Python/Jinja2 backend for server‐side templating and routing
• A variety of build and content‐generation scripts (JS, Python)
• CI/CD configurations for GitHub Actions and TeamCity
High-Level Architecture Components
A. Frontend Layer
1. Next.js/React pages (pages/, blocks/, components/)
2. Webpack/Babel build process (webpack.config.js, .babelrc)
3. Static assets (static/js, static/css, public/images, assets/)
4. “next-dev” server for development and “next-build-static” for SSG
B. Backend Layer
1. Python server (kotlin-website.py and src/)
2. Jinja2 templates (templates/, including includes/, pages/, inc/)
3. Content repositories:
– docs/topics (Markdown docs for Kotlin)
– data/*.yml (site configuration, navigation trees, releases, events)
– external repositories (grammar generator, coroutines, Dokka, etc.)
C. Build & Content Generation
1. Node scripts (scripts/dist, scripts/react-renderer, scripts/latest-news)
2. Python scripts (scripts/*.py for geolocating events/universities)
3. PDF generation (scripts/pdf.sh, src/pdf.py)
4. Search index generation (scripts/dist/lib/search)
5. Docker build context (dockerfiles/, docker-compose.yml)
D. Testing & Quality
1. Playwright e2e & visual tests (playwright.config.js, test/e2e/)
2. Snapshot and component tests (test/page, test/component)
3. CI pipelines
– GitHub Actions (.github/workflows) for linting, data validation
– TeamCity (.teamcity/) for building site artifacts and docs
E. External Services
1. Google Geocoding API for event/university location scripts
2. Algolia or other search (scripts/dist/lib/search/algolia.ts)
3. External content repos (kotlinx.coroutines, Dokka, kotlin-spec, etc.)
Relationships and Data Flows
• Editor changes Markdown/YAML → Build scripts (Node/Python) parse content →
Jinja2 templates + React components → Static HTML/CSS/JS output
• Next.js SSG produces interactive React pages; Python server serves non-Next.js pages
• CI pipelines trigger build scripts → run tests → deploy static artifacts to CDN/web server
• Docker images built for local/static e2e testing (nginx, app server, Playwright)
Key Architectural Patterns and Principles
• Static Site Generation (SSG) with Incremental React hydration
• Template-Driven Content (Jinja2 for Markdown + YAML → HTML)
• Separation of Concerns
• Data (docs/, data/)
• Presentation (templates/, blocks/, components/)
• Build/Automation (scripts/, dockerfiles/)
• Testing (test/, playwright)
• CI/CD as code: workflows in GitHub Actions + Kotlin‐DSL for TeamCity
Detail Level
• Every distinct script cluster (e.g., scripts/dist, scripts/latest-news, scripts/stdlib) as sub‐components.
• Template includes and content directories feeding into Python’s rendering engine.
• Separate interactive pages (Next.js) from purely templated pages (Jinja2).
• Testing layer showing Playwright containers and test suites consuming deployed artifacts.