# Kotlin website
[![Official project][project-badge]][project-url]
This repository is the source for [https://kotlinlang.org](https://kotlinlang.org).
* [Website structure](#website-structure)
* [Contribution](#contribution)
* [Local deployment](#local-deployment)
* [Feedback and issues](#feedback-and-issues)
<a id="project-structure"></a>
## Website structure
### Content
| Website page | Source files |
|-----------------------------------------------------------|----------------------------------------------------------|
| [Main page](https://kotlinlang.org/) | [pages/index.tsx](pages/index.tsx) |
| [Kotlin docs](https://kotlinlang.org/docs/home.html) | [docs/topics](docs/topics) |
| [Backend](https://kotlinlang.org/backend/) | [pages/backend](pages/backend) |
| [Multiplatform](https://kotlinlang.org/multiplatform/) | [pages/multiplatform](pages/multiplatform) |
| [Case Studies](https://kotlinlang.org/case-studies/) | [pages/case-studies](pages/case-studies) |
| [Community](https://kotlinlang.org/community/) | [pages/community](pages/community) |
| [Education](https://kotlinlang.org/education/) | [pages/education](pages/education) |
#### 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
| Website page | GitHub repository |
|--------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------|
| [Kotlin Multiplatform docs](https://kotlinlang.org/docs/multiplatform/get-started.html) | [kotlin-multiplatform-dev-docs](https://github.com/JetBrains/kotlin-multiplatform-dev-docs) |
| [Coroutines docs](https://kotlinlang.org/docs/coroutines-guide.html) | [kotlinx.coroutines](https://github.com/Kotlin/kotlinx.coroutines/) |
| [Serialization docs](https://kotlinlang.org/docs/serialization.html) | [kotlinx.serialization](https://github.com/Kotlin/kotlinx.serialization) |
| [Lincheck docs](https://kotlinlang.org/docs/lincheck-guide.html) | [kotlinx.lincheck](https://github.com/Kotlin/kotlinx-lincheck/) |
| [Dokka docs](https://kotlinlang.org/docs/dokka-introduction.html) | [dokka](https://github.com/Kotlin/dokka/) |
| [Library creators' guidelines](https://kotlinlang.org/docs/jvm-api-guidelines-introduction.html) | [api-guidelines](https://github.com/Kotlin/api-guidelines) |
| [Language specification](https://kotlinlang.org/spec/introduction.html) | [kotlin-spec](https://github.com/Kotlin/kotlin-spec) |
#### Auto-generated content
[API reference documentation](https://kotlinlang.org/api/latest/jvm/stdlib/) is generated based on comments in the Kotlin code.
Learn more about [documenting the Kotlin code](https://kotlinlang.org/docs/kotlin-doc.html).
The [Kotlin grammar reference](https://kotlinlang.org/grammar/) is generated by the [Kotlin grammar generator](https://github.com/Kotlin/website-grammar-generator) from the
[Kotlin grammar definition](https://github.com/Kotlin/kotlin-spec/tree/release/grammar/src/main/antlr).
### Configuration files
| Configuration | File |
|------------------------------------|--------------------------------------------------------------------------------------|
| Navigation and structure | [kr.tree](docs/kr.tree) for docs |
| Variables, such as release version | [v.list](docs/v.list) for docs and [releases.yml](data/releases.yml) for other pages |
## Contribution
You can contribute to the Kotlin website by sending us a pull request.
You can also [create a YouTrack issue](https://youtrack.jetbrains.com/newIssue?project=KT) to discuss your suggestion with the Kotlin team.
For the Kotlin documentation, follow [these guidelines on style and formatting](https://docs.google.com/document/d/1mUuxK4xwzs3jtDGoJ5_zwYLaSEl13g_SuhODdFuh2Dc/edit?usp=sharing).
For other pages, follow the complete syntax reference at the [kramdown site](https://kramdown.gettalong.org/syntax.html).
You can also include metadata fields. Learn more about it in the [Jekyll docs](https://jekyllrb.com/docs/front-matter/).
### Kotlin User Group
To add a Kotlin User Group (KUG), proceed the following way:
1. Open the configuration file [user-groups.yml](/data/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:
```yaml
position:
lat: 1.1111111
lng: 1.1111111
```
You can see the structure and types of the expected configuration in [the JSON schema](/data/schemas/user-groups.json).
Once you publish a pull request, the changes will be validated by [GitHub Actions Workflow](.github/workflows/validate-user-groups-data.yml) to prevent misconfiguration.
### Case Studies
To add a case study, do the following:
1. Fill the case study info in the [case-studies.yml](/data/case-studies/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](https://example.com), 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](/data/schemas/case-studies.json) and in the [example file](/data/case-studies/_case-study.example.yaml).
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](.github/workflows/validate-case-studies-data.yml) 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](https://youtrack.jetbrains.com/issue/KT-47049).
See [Local development](#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](#local-development).
- Your Node.js version matches `.nvmrc` (using [`nvm`](https://github.com/nvm-sh/nvm) or alternatives like [`n`](https://github.com/tj/n), [`asdf`](https://github.com/asdf-vm/asdf), [`mise`](https://github.com/jdx/mise)).
To generate a PDF version of the Kotlin documentation:
1. Download and extract the `pages.zip` artifacts from the [Build site pages CI build](https://buildserver.labs.intellij.net/buildConfiguration/Kotlin_KotlinSites_KotlinlangTeamcityDsl_BuildSitePages) into the `dist` directory:
```bash
mkdir -p dist
unzip pages.zip -d dist
```
This will provide the required `dist/docs` directory.
2. Run:
```bash
yarn install --frozen-lockfile
cd scripts/dist && yarn install --frozen-lockfile && cd ../..
yarn generate-pdf
```
The PDF will be created at `assets/kotlin-reference.pdf`. Generation may take several minutes. (Team members can also run or download artifacts directly from the [PDF Generator CI build](https://buildserver.labs.intellij.net/buildConfiguration/Kotlin_KotlinSites_KotlinlangTeamcityDsl_PdfGenerator)).
For more details, see [scripts/pdf/README.md](scripts/pdf/README.md).
## Feedback and issues
You can:
* Report an issue to [our issue tracker](https://youtrack.jetbrains.com/newIssue?project=KT).
* Share feedback in the [#kotlin-website](https://kotlinlang.slack.com/archives/C02B3PECK6E) channel in our Kotlin public Slack ([get an invite](https://surveys.jetbrains.com/s3/kotlin-slack-sign-up)).
[project-url]: https://confluence.jetbrains.com/display/ALL/JetBrains+on+GitHub
[project-badge]: https://jb.gg/badges/official.svg
[slack-url]: https://slack.kotlinlang.org
## Local development
For the frontend development, you need to connect to the WebTeam registry.
Visit [the registry](https://jetbrains.team/p/wt/packages/npm/npm) 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](http://localhost:3000).
## Pages on Next.js
You can find all pages in the [pages](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:
```tsx
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:
```tsx
<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](https://buildserver.labs.intellij.net/buildConfiguration/Kotlin_KotlinSites_KotlinlangTeamcityDsl_BuildReferenceDocs?branch=&mode=builds#all-projects) 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.