Kotlin website

This repository is the source for https://kotlinlang.org.

• Website structure
• Contribution
• Local deployment
• Feedback and issues

Website structure

Content

Sources in different repositories

Source files for the language specification and the docs for Kotlin Multiplatform, coroutines, serialization, lincheck, Dokka, and Library creators' guidelines are stored in separate repositories

Auto-generated content

API reference documentation is generated based on comments in the Kotlin code. Learn more about documenting the Kotlin code.

The Kotlin grammar reference is generated by the Kotlin grammar generator from the Kotlin grammar definition.

Configuration files

Contribution

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.

For other pages, follow the complete syntax reference at the kramdown site. You can also include metadata fields. Learn more about it in the Jekyll docs.

Kotlin User Group

To add a Kotlin User Group (KUG), proceed the following way:

1. Open the configuration file user-groups.yml.

2. Find a suitable section among existing ones.

3. 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 true value if the group is online only.
   • position, the geo-position of the group, defined by pair of keys: lat and lng. It better to run scripts/user_group.

4. If the group is not virtual, you also need to specify a group's position. Add manually position key with the lat and lng values, as next:

   position:
     lat: 1.1111111
     lng: 1.1111111
   

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.

Case Studies

To add a case study, do the following:

1. Fill the case study info in the case-studies.yml with the next:

   • id, a unique identifier for the case study.
   • type, the case study category: either multiplatform or backend.
   • description, a markdown-enabled text description of the case study (supports # header bold and links, paragraphs are made with two new lines).
   • logo (optional), an array of 0-2 image paths relative to the /public/ directory.
   • signature (optional), an object with name and position fields for the quote author.
   • isExternal (optional), a boolean indicating if the case story is from an external source (default: false).
   • link (optional), a URL to the full case story.
   • linkText (optional), custom text for the link (default: "Read the full story").
   • linkStyle (optional), either button or text for the link style.
   • platforms (optional), an array of platform tags such as android, ios, desktop, frontend, backend, or compose-multiplatform.
   • media (optional), a media object with type set to either youtube (with videoId) or image (with path relative to /public/).
   • featuredOnMainPage (optional), a boolean to mark the case as featured on the main page.

   You can see the structure and types of the expected configuration in the JSON schema and in the example file.

2. The order of case studies in the file defines the order of their appearance on the website. Place new case studies accordingly.

3. Publish the changes by creating a pull request. The changes will be validated by GitHub Actions Workflow to prevent misconfiguration.

Local deployment

Currently, there is no way to deploy the full Kotlin website locally. This ticket tracks the effort of adding support for local testing: KT-47049. See Local development below for running the website locally.

You can contribute to the Kotlin website by sending us a pull request.

PDF Generation

Before you begin, make sure your local environment is connected to the WebTeam registry. Learn more about it in the section below.

To generate a PDF version of the Kotlin documentation:

1. Download and extract the pages.zip artifacts from the Build site pages CI build into the project root. This will provide the dist/docs directory.
2. Run:

   yarn install
   cd scripts/dist && yarn install && cd ../../
   yarn generate-pdf
   

The PDF will be created at assets/kotlin-reference.pdf. Generation may take several minutes.

For more details, see scripts/pdf/README.md.

Feedback and issues

You can:

• Report an issue to our issue tracker.
• Share feedback in the #kotlin-website channel in our Kotlin public Slack (get an invite).

Local development

For the frontend development, you need to connect to the WebTeam registry. Visit the registry page in Space:

• On the top right, click Connect;
• Click Generate personal token;
• Copy your personal token.
• Add your personal token to the environmental variable. This step differs based on your OS.

For macOS:

Add your token to the ~/.zshenv file:

• Open the Terminal;
• Use this command to access .zshenv file nano ~/.zshenv;
• Replace your_token with your actual Space token and use this command to add an environment variable: export WEBTEAM_UI_NPM_TOKEN=yourtoken. Then install frontend dependencies npm install.

# install frontend dependencies
yarn install

# at first start you need to build the static
yarn run next-build-static

# run development server
yarn start

Now you can open the website at http://localhost:3000.

Pages on Next.js

You can find all pages in the pages directory.

Projects structure

• 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

Use next/image for raster images (PNG, JPG, WebP). Static imports provide automatic width/height:

import Image from 'next/image';
import myImage from './my-image.png';

<Image src={myImage} alt="..." />

For SVGs displayed as images, use a plain <img> tag with the public path:

<img src="/images/path/to/icon.svg" alt="" />

Tests

We use Playwright for writing e2e and Screenshot tests. See https://playwright.dev/ for more details.

Prerequirements

To run tests locally:

1. Install supported browsers:

   npx playwright install
   

2. Start Dev Server.

Run Tests

• yarn test to run all tests in headless mode locally.
• yarn test:e2e to run e2e tests locally, visual tests are also included.
• yarn test:e2e:skip-visual to run e2e tests without visual tests locally.
• yarn test:production to run the subset of e2e tests that are meant to check the production locally.

There are also additional options to run tests:

• yarn run test:e2e:ci or yarn test:production:ci to run tests in CI environments.
• yarn test:e2e:headed or yarn test:production:headed to run tests in headed mode locally.
• yarn test:e2e:debug or yarn test:production:debug to run e2e tests in headed mode with debug locally.

To ease the process of adding and maintaining e2e tests:

• yarn test:e2e:new to generate the test for the user interactions.
• yarn test:e2e:update to update screenshots when something on page has changed intentionally.
• yarn test:e2e:screenshots to run e2e tests with screenshots across different breakpoints (breakpoints-v2).

Write Tests

To write e2e test, create spec file /test/e2e/*your-page*.spec.js.

WebHelp tests

Some e2e tests focus on preventing regressions in the WebHelp components used to build documentation in the /docs section of kotlinlang.org. To run these tests locally, follow the next steps:

1. Create the dist folder in the project.
2. Open the last successful build of Reference Docs on TeamCity.
3. Download the artifacts of this build and place them in the dist folder.
4. Run the tests locally with the following command yarn run test:e2e
5. Run the tests in docker container with the following command docker compose -f docker-compose-e2e.yml up --build --exit-code-from playwright

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:

1. Create the libs folder in the project.
2. Open the last successful build of each API reference on TeamCity.
3. Download the artifacts of these builds and place them in the libs folder by their name, for example, kotlinx.coroutines.
4. Up containers ./scripts/dokka/up.sh.
5. Run test inside container ./scripts/dokka/run.sh or on the host with one of the scripts below.