This repository is the source for https://kotlinlang.org.
|Website page||Source files|
Sources in different repositories
Source files for the language specification and the docs for coroutines, lincheck, Dokka, and Library creators' guidelines are stored in separate repositories
|Website page||GitHub repository|
|Library creators' guidelines||api-guidelines|
|Navigation and structure||kr.tree for docs and _nav.yml for other pages|
|Variables, such as release version||v.list for docs and releases.yml for other pages|
|Community events on the map||events.xml|
|Video list (outdated)||videos.yml|
The Kotlin website uses Jinja2 templates from the templates directory.
Note that all Markdown files, except for docs, are processed as Jinja templates before HTML conversion.
This allows using all Jinja benefits for Markdown (for example, building URLs with the
You can contribute to the Kotlin website by sending us a pull request. You can also create a YouTrack issue to discuss your suggestion with the Kotlin team.
For the Kotlin documentation, follow these guidelines on style and formatting.
Kotlin User Group
To add a Kotlin User Group (KUG), proceed the following way:
Open the configuration file user-groups.yml.
Find a suitable section among existing ones.
Add into the selected section a new group with the following keys:
name, the name of the group.
country, the name of the country where the group is located. In the case of a virtual group, please use "International" for that.
url, the link to the group's web page.
isVirtual, set this key with
truevalue if the group is online only.
position, the geo-position of the group, defined by pair of keys:
lng. It better to run
If the group is not virtual, you also need to specify a group's position. You can do it manually adding
positionkey with the
lngvalues, as next:
position: lat: 1.1111111 lng: 1.1111111
or, to run the geo script (
scripts/user_groups_geolocator.py) that will do it for you. You need to obtain GOOGLE_API_KEY and then run the following script:
$ GOOGLE_API_KEY="..." python scripts/universities_geolocator.py
You can find more details about
GOOGLE_API_KEYparam in this article by Google. The manual way sometimes is better, because it allows you to specify the position more precisely.
You can see the structure and types of the expected configuration in the JSON schema. Once you publish a pull request, the changes will be validated by GitHub Actions Workflow to prevent misconfiguration.
To add an event to the Community Events, do the following:
- Fill the event info in the events.yml with the next:
lang, two-letter code considering ISO 639-1 format.
startDate, in the format 'yyyy-mm-dd'.
endDate, in the format 'yyyy-mm-dd'. For the on day event fill the same date as in the startDate.
location, in the form of 'City, Country'. You can omit it for an online event.
online, set this key with
truevalue in case of online event.
speaker, the speaker's name.
title, event's title.
subject, a title of a talk.
url, link to the event web page. You can see the structure and types of the expected configuration in the JSON schema.
- Publish the changes creating a pull request. The changes will be validated by GitHub Actions Workflow to prevent misconfiguration.
Currently, there is no way to deploy the Kotlin website locally. This ticket tracks the effort of adding support for local testing: KT-47049.
You can contribute to the Kotlin website by sending us a pull request.
Feedback and issues
- Report an issue to our issue tracker.
- Share feedback in the #kotlin-website channel in our Kotlin public Slack (get an invite).
- Email us at email@example.com.
Pages on Next.js
You can find all pages in the pages directory.
- Components. The building blocks.
- Blocks. Blocks are groups of components joined together to form a relatively complex, distinct section of an interface.
- Pages. Each page is associated with a route based on its file name.
Images in Next.js
Notice that using
next/image is not possible because Next.js does not support importing images to HTML files (SSG).
Use Img and Svg components from "next-optimized-images" instead.
We use Playwright for writing e2e and Screenshot tests. See https://playwright.dev/ for more details.
To run tests locally:
Install supported browsers:
npx playwright install
Start Dev Server.
yarn testto run all tests in headless mode locally.
yarn test:e2eto run e2e tests.
yarn test:e2e:headedto run e2e tests in headed mode.
yarn test:e2e:debugto run e2e tests in headed mode with debug.
yarn test:e2e:newto generate the test for the user interactions.
yarn ci:e2eto run e2e test in CI environments.
To write e2e test, create spec file
API references tests
Some tests focus on protecting the HTML markup of API references from being corrupted by the KTL components in the Dokka template's extension. To run these tests locally, follow the next steps:
- Create the
libsfolder in the project.
- Open the last successful build of each API reference on TeamCity.
- Download the artifacts of these builds and place them in the
libsfolder by their name, for example,
- Up containers
- Run test inside container
./scripts/dokka/run.shor on the host with one of the scripts below.
To run visual testing, apply one of the next scripts:
yarn test:visualto compare pages with base screenshots. Base screenshots are in
yarn test:visual:headedto run visual test in headed mode.
yarn test:visual:updateto update all screenshots, for example, when the page has been changed.
yarn ci:visualto run visual test in CI environments.