Kotlin website

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

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

Website structure

Content

Website page	Source files
Main page	templates/pages/index.html
Kotlin docs	docs/topics
Community	pages/community
Education	templates/pages/education

Note that source files for the server-side landing page and Kotlin Multiplatform landing page are not publicly available.

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
Coroutines docs	kotlinx.coroutines
Lincheck docs	kotlinx.lincheck
Dokka docs	Dokka
Library creators' guidelines	api-guidelines
Language specification	kotlin-spec

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

Configuration	File
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

Templates

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 url_for function).

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. You can do it manually adding position key with the lat and lng values, 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_KEY param 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.

Community Events

To add an event to the Community Events, do the following:

1. 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 true value 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.
2. Publish the changes 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 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

You can:

• 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 doc-feedback@kotlinlang.org.

Local development

preliminaries: python3 installed

# install frontend dependencies
yarn install

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

# run NextJS server
yarn run next-dev

# run webpack dev server for everything else
yarn start

# install dependencies for the python server
pip  install --no-build-isolation -r requirements.txt

# run python server
python3 kotlin_website.py

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

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

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.

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.

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-statics.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.