# JetBrains/kotlin-web-site: structure, content workflow, and setup limits

> JetBrains/kotlin-web-site is the TypeScript source repository for kotlinlang.org, combining documentation pages, structured data, generated references, and publication components. It fits contributors who can follow several content pipelines, but the README does not provide enough local setup detail for a complete first deployment.

**JetBrains/kotlin-web-site** — The Kotlin programming language website

- Repository: https://github.com/JetBrains/kotlin-web-site
- Website: http://kotlinlang.org
- Stars: 1,627 · Forks: 4,580
- Language: TypeScript
- License: Apache-2.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/jetbrains-kotlin-web-site

## What lives in JetBrains/kotlin-web-site

This repository solves a large publishing problem rather than a Kotlin application-development problem. It is the source for kotlinlang.org, so changes to language pages, documentation navigation, community listings, case studies, and other site sections converge in one project. The documented page map is concrete: `pages/index.tsx` supplies the main page, `docs/topics` supplies Kotlin documentation, and dedicated page areas cover backend, multiplatform, case studies, community, and education.

The intended users are contributors who understand website code and editorial workflows. Kotlin developers looking for the compiler, standard library, examples, or documentation projects should not mistake this repository for those artifacts. Its `package.json` identifies it as `kotlinlang.org`, with a placeholder version of `0.0.0`, while the repository layout includes `pages/`, `components/`, `blocks/`, `assets/`, `public/`, `data/`, and documentation trees. Based on that layout, this is a site application and content system rather than a reusable Kotlin library.

One important boundary is that the published site is broader than this repository. The README assigns Multiplatform documentation, coroutines documentation, serialization documentation, Lincheck documentation, Dokka documentation, library creator guidelines, and the language specification to separate repositories. API references and grammar documentation add further generated content. Contributors therefore need to identify the correct source before editing.

## TypeScript pages, documentation trees, and generated references

The site combines several publishing mechanisms. Programmatic pages are represented by TypeScript and TSX files under `pages/`, while reusable presentation code is separated into `components/`, `blocks/`, `hooks/`, and `utils/`. Files such as `next.config.js`, `webpack.config.js`, `postcss.config.js`, `tsconfig.json`, and `playwright.config.ts` indicate a frontend project with build, styling, and browser-test configuration. The README does not explain the exact runtime sequence, so the repository layout provides the available basis for this description.

Documentation has its own route structure. `docs/kr.tree` controls documentation navigation and structure, while `docs/v.list` supplies variables such as the release version. Other pages use `data/releases.yml`. This separation means a documentation fix, a landing-page release reference, and generated API output may involve different files and repositories.

Generated content is another major path. The README states that the JVM standard library API reference is generated from comments in Kotlin code. It also says the Kotlin grammar reference is produced by the `website-grammar-generator` from a grammar definition maintained in `kotlin-spec`. Editing an API page directly or changing the grammar documentation in this repository may therefore be the wrong approach. The source needs to be identified first.

For contributors, this mixed architecture offers clear ownership boundaries but adds coordination work. A documentation correction, a new generated reference, and a homepage change do not necessarily follow the same publication path.

## A first contribution through user-groups.yml

The visible README text does not include commands from its local deployment section. It gives no package manager, startup command, required Node version, or local URL, and `.nvmrc` is present without its contents. This article therefore does not invent a local deployment command. The first fully documented real use is adding a Kotlin User Group through structured configuration.

Open `data/user-groups.yml` and find the suitable section. Add an entry with `name`, `country`, `url`, `isVirtual`, and `position`. The README specifies `International` as the country value for a virtual group. For a physical group, it says to run `scripts/user_group`, which is also the preferable way to obtain the geographic position, although contributors may enter it manually. The expected structure for a manual position is:

```yaml
position:
  lat: 1.1111111
  lng: 1.1111111
```

Before opening a pull request, compare the entry with `data/schemas/user-groups.json`, which defines the expected types and structure. The README states that `.github/workflows/validate-user-groups-data.yml` validates changes after a pull request is published. The stated acceptance condition is schema validation rather than a manually judged page appearance.

This workflow is a good first contribution because it touches a narrowly defined configuration file. It does not demonstrate how to start the complete site locally, so success with a user group should not be treated as proof that the frontend development environment is understood.

## Separate repositories as the alternative contribution path

The clearest alternative to changing this repository is to change the repository that owns the content. For the language specification, the README directs contributors to `kotlin-spec`. Multiplatform development documentation belongs in `kotlin-multiplatform-dev-docs`, coroutines documentation in `kotlinx.coroutines`, serialization documentation in `kotlinx.serialization`, Lincheck documentation in `kotlinx.lincheck`, Dokka documentation in `dokka`, and library creator guidelines in `api-guidelines`.

This is a different approach from treating kotlinlang.org as one editable corpus. The website repository configures and publishes site content, but some subject documentation remains close to the code, specification, or library team that owns it. The same separation applies to generated API and grammar material: source comments and the grammar definition feed generators rather than serving as ordinary page edits.

The trade-off is clear. Editing the website repository offers direct access to site-level content and configuration, but it can create the wrong source boundary. Following the README's repository map may require cross-repository knowledge, yet it preserves ownership and keeps generated or externally maintained content in its designated place. Contributors should choose the path based on content origin, not on which repository produces the final public URL.

## Configuration and validation constraints

The configuration files reveal several places where a small-looking edit can fail validation. User groups have both a YAML source, `data/user-groups.yml`, and a JSON schema at `data/schemas/user-groups.json`. GitHub Actions performs dedicated validation for that data. Case studies are maintained in `data/case-studies/case-studies.yml`, with required fields including a unique `id`, a `type` of either `multiplatform` or `backend`, and a Markdown-enabled `description`; optional `logo` and `signature` structures mean a YAML edit can also depend on precise field types and relative paths.

The README distinguishes two authoring formats. Kotlin documentation follows its own style and formatting guidelines, while other pages use kramdown syntax and can include Jekyll front matter metadata. Although the site is implemented primarily in TypeScript, that does not mean every content page is a React component. Contributors need to inspect the target page's source format before editing it.

There are also redirect files, search configuration, release data, scripts, test files, Docker Compose end-to-end configuration, and multiple static directories. The presence of `docker-compose-e2e.yml` and `playwright.config.ts` indicates an end-to-end testing setup, but the README does not explain how to launch it. Claiming that all of these checks are part of one command would be unsupported.

## Maintenance, releases, and Apache-2.0

The repository is not archived, and its recorded last push was on 2026-10-16. It has no GitHub releases, so there is no repository release cadence to use as an upgrade signal. Maintenance activity must instead be judged from commit history, issue handling, dependency changes, and pull requests, while contributors should distinguish website application updates from changes in the separate documentation repositories.

The stated license is Apache-2.0, recorded both in the repository metadata and `package.json`. That is relevant when reusing code or distributing modified copies, because the license includes permissions and conditions that must be followed. This article does not interpret the license for a specific legal situation.

Upgrade cost is tied to a broad frontend dependency surface. The visible dependency list includes React UI libraries, WebTeam components, build tools, search integration, and site-specific packages. A dependency update may touch styling, browser compatibility, content rendering, or generated search behavior. The repository also targets a browserslist configuration that excludes Internet Explorer and specifies Edge versions above 18. The README does not provide an upgrade procedure, compatibility matrix, or support window, so adopting it does not remove the need to read the current configuration files.

## When this website repository is the wrong choice

It is the wrong repository for compiler development, standard library implementation, library bug reports, or changes to the Kotlin specification. Those tasks belong elsewhere even when the final result appears on kotlinlang.org. It is also a poor fit for someone seeking a small static site starter, because the repository contains website-specific data, redirects, generated documentation integrations, JetBrains UI packages, search configuration, and multiple content pipelines.

The largest practical limitation is incomplete setup documentation in the visible README text. Although files such as `.nvmrc`, `.env.sample`, `package.json`, and `yarn.lock` exist, their existence does not confirm a working install sequence. `.env.sample` includes `NODE_ENV`, `INDEX_NAME`, `KEY_FILE_LOCATION`, `SEARCH_KEY`, `SEARCH_USER`, and `NEXT_PUBLIC_SITE_URL`, which indicates that at least some site behavior depends on environment configuration. The sample values for `INDEX_NAME`, `KEY_FILE_LOCATION`, `SEARCH_KEY`, and `SEARCH_USER` are placeholders rather than ready credentials.

Another limitation is generated-content ownership. Search indexing may depend on external services and configuration, while API and grammar pages depend on upstream generation. A clean local page render would not necessarily prove that those integrations work. Contributors should verify the deployment path, environment values, upstream source repository, and validation workflow before treating a local edit as publication-ready.

## Conclusion

Adopt this repository if you intend to maintain kotlinlang.org and can work within its mixed TypeScript, documentation, YAML, and generated-content pipelines. Do not choose it merely to learn Kotlin or host a small documentation site, because its scope is JetBrains' public website and the README does not document a complete local installation. Verify first that `package.json`, `.nvmrc`, `.env.sample`, and the missing local deployment instructions provide a startup path that matches your environment.

## FAQ

### What is JetBrains/kotlin-web-site used for?

It is the source repository for kotlinlang.org. It contains site pages, Kotlin documentation navigation, structured data, components, and configuration for published content.

### How do I run the kotlinlang.org site locally?

The visible README text does not include its local deployment instructions, so it does not provide a confirmed startup command or local URL. The repository does contain `.nvmrc`, `.env.sample`, `package.json`, and `yarn.lock` as relevant setup files.

### Where should I change Kotlin Multiplatform or coroutines documentation?

The README assigns Multiplatform development documentation to `kotlin-multiplatform-dev-docs` and coroutines documentation to `kotlinx.coroutines`. Changes should be made in those source repositories rather than assumed to belong in the website repository.

## Sources

- [Issues](https://github.com/JetBrains/kotlin-web-site/issues)
- [JetBrains/kotlin-web-site on GitHub](https://github.com/JetBrains/kotlin-web-site)
- [License: Apache-2.0](https://github.com/JetBrains/kotlin-web-site/blob/master/LICENSE)
- [Project website](http://kotlinlang.org)
- [README](https://github.com/JetBrains/kotlin-web-site/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/jetbrains-kotlin-web-site