Kotlin website
This repository is the source for https://kotlinlang.org.
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 Mobile landing page are not publicly available.
Sources in different repositories
Source files for coroutine docs, and language specification are stored in separate repositories:
Website page | GitHub repository |
---|---|
Coroutine docs | kotlinx.coroutines |
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. If you're going to propose a big change, discuss your idea with the team via [email protected].
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 in the Jekyll docs.
Kotlin User Group
To add a Kotlin User Group, 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 followed 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 withtrue
value if the group is online only.position
, the geo-position of the group, defined by pair of keys:lat
andlng
. It better to runscripts/user_group
- If the group is not virtual, you also need to specify a group's position.
You can do it manually adding
position
key with thelat
andlng
values, as next:or, to run the geo script (position: lat: 1.1111111 lng: 1.1111111
scripts/user_groups_geolocator.py
) that will do it for you. You need to obtain GOOGLE_API_KEY and then run the following script:More details about GOOGLE_API_KEY param you can find in this article. The manual way sometimes is better, because it allows you to specify the position more precisely.$ GOOGLE_API_KEY="..." python scripts/universities_geolocator.py
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, follow the instruction below.
- 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 withtrue
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.
- 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:
- Share feedback in the #docs-revamped channel in our Kotlin public Slack (get an invite).
- Report an issue to our issue tracker.
- Email us at [email protected].
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:
- Install supported browsers:
npx playwright install
- Start Dev Server.
Run Tests
yarn test
to run all tests in headless mode locally.yarn test:e2e
to run e2e tests.yarn test:e2e:headed
to run e2e tests in headed mode.yarn test:e2e:debug
to run e2e tests in headed mode with debug.yarn test:e2e:new
to generate the test for the user interactions.yarn test:visual
to compare pages with base screenshots. Base screenshots are in test/visual.yarn test:visual:headed
to run visual test in headed mode.yarn test:visual:update
to update all screenshots, for example when the page has changed.yarn ci:e2e
to run e2e test in CI environments.yarn ci:visual
to run visual test in CI environments.
Write Tests
To write e2e test: Create spec file /test/e2e/your-page.spec.js