kyma-project · grego952 · Nov 21, 2025 · Oct 31, 2025 · Oct 31, 2025 · Nov 12, 2025
@@ -1,49 +1,85 @@
 # User Documentation
 
-Open-source Kyma and Kyma module user documentation is displayed at [`https://kyma-project.io`](https://kyma-project.io/#/). The website uses [docsify](https://docsify.js.org/#/) as a documentation site generator.
+Open-source Kyma and Kyma module user documentation is displayed at [`https://kyma-project.io`](https://kyma-project.io/#/). The website uses [VitePress](https://vitepress.dev/) as a documentation site generator.
 
 The overarching Kyma content is pulled from the `/docs` folder in the `/kyma` repository. Module documentation is pulled from the `/docs/user` folder in respective module repositories.
 
-After initialization, to run, docsify uses the following files located in the `/docs` folder in the `/kyma` repository:
+After initialization, to run, VitePress uses the following files in the `/kyma` repository:
 
-- `index.html` for configuration
-- `README.md` as the home page
+- `config.mjs` for configuration, including configuration of all sidebars 
+- `index.md` as the home page
+- `deploy.yml` to deploy documentation to the website
 - `.nojekyll` preventing GitHub Pages from ignoring files that begin with an underscore
-- `_sidebar.md` listing all Markdown documents to be displayed and ruling navigation between those documents on the website
 
 ## Publish a Document from the `/kyma` Repository
 
 To publish a document located in the `/kyma` repository, follow these steps:
 
 1. Create a pull request adding your content to a Markdown file located in the `/docs` folder.
-2. Add a new `_sidebar.md` file including a link to your document, or update an existing `_sidebar.md` to include it.
+2. Go to [`/kyma/.vitepress/config.mjs`](https://github.com/kyma-project/kyma/blob/main/.vitepress/config.mjs#L138) and provide your document details in the **sidebar** element, under **themeConfig**. Use the following pattern:
+
+   ```bash
+    {
+       text: 'Troubleshooting',
+       link: '/04-operation-guides/troubleshooting/README',
+    },
+    ```
+
+3. Run the [Deploy VitePress site to GitHub Pages](https://github.com/kyma-project/kyma/actions/workflows/deploy.yml) or wait for the CronJob to start it (every day at midnight).
+4. Make sure that the `public` folder in the root of the `/kyma` repository is deleted after the build. If not, delete it manually to clean up the environment.
 
 ## Publish a Document from an Existing Module Repository
 
 To publish a document located in an existing module repository, follow these steps.
 
 1. Create a pull request adding your content to a Markdown file located in the `/docs/user` folder in your module repository.
-2. In the `docs/user` folder, add a new `_sidebar.md` file including a link to your document, or update the existing `_sidebar.md` to include it.
+2. Update the `_sidebar.ts` file located in the `/docs/user` folder in the module repository, including a link to your document.
+3. In the `/kyma` repository, run the [Deploy VitePress site to GitHub Pages](https://github.com/kyma-project/kyma/actions/workflows/deploy.yml) or wait for the CronJob to start it (every day at midnight).
+4. Make sure that the `public` folder in the root of the `/kyma` repository is deleted after the build. If not, delete it manually to clean up the environment.
 
 ## Publish a Document from a New Module Repository
 
 To publish a document located in a new module repository, follow the steps from [Publish a document from an existing module](#publish-a-document-from-an-existing-module-repository). Once completed, do the following:
 
-1. In the `/kyma` repository, open the<!-- markdown-link-check-disable-line --> [`/kyma/docs/_sidebar.md`](https://github.com/kyma-project/kyma/blob/main/docs/_sidebar.md) file and under **Modules**, add a link to your module documentation main page.
-2. Update `index.html` by adding a new **alias** entry in the **<body>** part. Use the following pattern:
+1. In the `/kyma` repository, open the<!-- markdown-link-check-disable-line --> [`/kyma/vitepress/config.mjs`](https://github.com/kyma-project/kyma/blob/main/.vitepress/config.mjs).
+2. Add `import {YOUR_MODULE_NAME}Sidebar from '../docs/external-content/{YOUR_MODULE_NAME}/docs/user/_sidebar';` as the next import line.
+3. Provide your module details in the **sidebar** element, under **themeConfig**. Use the following pattern:
 <!-- markdown-link-check-disable -->
-    ```html
-    alias: {
-    '/{MODULE_REPOSITORY_NAME}/(.*)': 'https://raw.githubusercontent.com/{GITHUB_PROJECT_NAME}/{MODULE_REPOSITORY_NAME}/main/docs/$1',
-    }, 
-    ```
+   ```mjs
+   {
+      text: 'My Module',
+      link: '/external-content/my-module/docs/user/README.md',
+      collapsed: true,
+      items: makeSidebarAbsolutePath(
+        myModuleSidebar,
+        'my-module',
+      ),
+   },
+   ```
 
-    For example:
+   4. In the `/kyma` repository, add the module repository name to the [`deploy.yml`](https://github.com/kyma-project/kyma/blob/main/.github/workflows/deploy.yml) file under the **jobs.copy-docs.strategy.matrix.repository** element. For example:
 
-    ```html
-    alias: {
-    '/serverless-manager/(.*)': 'https://raw.githubusercontent.com/kyma-project/serverless-manager/main/docs/$1',
-    }, 
-    ```
+   ```yaml
+   jobs:
+     copy-docs:
+       strategy:
+         matrix:
+           repository:
+             - btp-manager
+             - istio
+             - serverless
+             - {YOUR_MODULE_REPO}
+   ```
 <!-- markdown-link-check-enable -->
-> **CAUTION:** When you update navigation paths in documentation, make sure you check all `_sidebar.md` files that may be affected.
+> **CAUTION:** When you update navigation paths in documentation, make sure you check all `_sidebar.ts` files that may be affected.
+
+5. Run the [Deploy VitePress site to GitHub Pages](https://github.com/kyma-project/kyma/actions/workflows/deploy.yml) or wait for the CronJob to start it (every day at midnight).
+6. Make sure that the `public` folder in the root of the `/kyma` repository is deleted after the build. If not, delete it manually to clean up the environment.
+
+## Execute Prettier
+
+Prettier helps keep your code nicely formatted. The project is set up to use it automatically, as long as you're using Visual Studio Code with the Prettier plugin. However, it's configured to run during Git commits. So, if you're not using the integrated Git in VSCode for commits, you'll need to run it manually with this command:
+
+```bash
+npx prettier --config ./.prettierrc --ignore-path ./.prettierignore --write '**/*.{ts,tsx,mjs,js,jsx,json,html,css,yaml,md}'
+```
@@ -80,7 +80,7 @@ Suppose that it is only the part containing the certificate information that is
 >**NOTE** The following panels are not rendered correctly when indented. Use them only in the docs that are displayed on the website.
 For the docs not rendered on the website, use **NOTE**, **TIP**, and **CAUTION**.
 
-Panels are colorful containers that call out important or additional information within a topic. The Kyma documentation uses the [Flexible Alerts](https://github.com/fzankl/docsify-plugin-flexible-alerts) docsify plugin for the panels' formatting. To call attention to a specific note, a word of caution or a tip, use the  [!NOTE], [!TIP], and [!WARNING] panels. Use:
+Panels are colorful containers that call out important or additional information within a topic. The Kyma documentation uses the VitePress customized alerts. To call attention to a specific note, a word of caution or a tip, use the  [!NOTE], [!TIP], and [!WARNING]. Use:
 
 - The blue [!NOTE] panel to point to something specific, usually relating to the topic.
 - The orange [!WARNING] panel to call attention to something critical that can cause inoperable behavior.

@@ -4,11 +4,11 @@ Tabs and toggles allow you to render several versions of a given section in one
 
 For example, you can use tabs and/or documentation toggle to include instructions for different operating systems (OS) in one guide, or to describe installation guides that differ only in a few steps.
 
-As described in the document, tabs are a docsify-specific form of presenting content versions in Markdown. Toggles use HTML within a Markdown document.
+As described in the document, VitePress uses a docsify-specific form of presenting content versions in Markdown. Toggles use HTML within a Markdown document.
 
-## Docsify Tabs
+## Customized Tabs
 
-To display tabbed content from Markdown, `kyma-project.io` uses the [docsify-tabs plugin](https://jhildenbiddle.github.io/docsify-tabs/#/) from [docsify.js](https://docsify.js.org/#/).
+To display tabbed content from Markdown, kyma-project.io uses the VitePress-customized tabs.
 
 You define a tab set using the `tabs:start` and `tabs:end` HTML comments. For detailed guidelines, see [docsify-tabs: Usage](https://jhildenbiddle.github.io/docsify-tabs/#/?id=usage).
 

@@ -1,43 +1,32 @@
 # Documentation Preview
 
-Before you publish new documentation on the Kyma website, you can preview your changes to see if the formatting of the text is correct, images fit well, and links work as expected.
+Before you publish new documentation on the Kyma website, you can preview your changes to see if the formatting of the text is correct, images fit well, and links work as expected. To do that, see the following steps:
 
-That is possible thanks to the [**docsify preview feature**](https://docsify.js.org/#/quickstart?id=preview-your-site) supported by [docsify](https://docsify.js.org/#/).
+1. Go to the [`kyma/hack`](https://github.com/kyma-project/kyma/tree/main/hack), and execute the `copy_external_content.sh` script:
+
+   ```bash
+   ./copy_external_content.sh
+   ```
+   This process copies the `docs/user` folder and `docs/assets` folder from the repositories specified in the `sh` file. Everything is copied to the `external-content` folder, and all existing files are overwritten.
 
-## Prerequisites
+   > [!NOTE]
+   > If you want to preview a new module that you added, you must add it to the `REPOS` section in `copy_external_content.sh`.
 
-You have installed docsify-cli.
+2. You can run your preview in Development or Production-Like mode.
 
-To install docsify-cli, run `npm i docsify-cli -g`.
+   - To check if your documentation works locally, use Development mode by executing the following commands:
 
-## Steps
+   ```bash
+   npm install
+   npm run docs:dev
+   ```
 
-To preview content on the Kyma website, save your changes and run the local server.
+   - To check if the build is executed properly and the documentation is displayed correctly on the website, run Production-Like mode by executing the following commands:
 
-1. Run `docsify serve docs` in the `/kyma` repository.
-<!-- markdown-link-check-disable-next-line -->
-2. Preview `https://kyma-project.io` in your browser on `http://localhost:3000`.
+   ```bash
+   npm run docs:build
+   npm run docs:preview
+   ```
 
-## Preview Module Documentation
-
-1. In your module repository, create a pull request with documentation changes.
-2. In the `/kyma` repository, go to the `docs/index.html` file and change the value of the **alias** parameter for your module. By default, the value points to the raw version of the `/docs` folder on the main branch of your module repository. Change the value to point to the raw version of the respective folder on your branch. Use the following pattern:
-
-  ```html
-  alias: {
-  '/{MODULE_REPOSITORY_NAME}/(.*)': 'https://raw.githubusercontent.com/{YOUR_GITHUB_USERNAME}/{FORKED_MODULE_REPOSITORY_NAME}/{BRANCH_TO_PREVIEW}/docs/$1',
-  }, 
-  ```
-
-  For example:
-
-  ```html
-  alias: {
-  '/istio/(.*)': 'https://raw.githubusercontent.com/kymauser/istio/docu-update/docs/$1',
-  },
-  ```
-
-3. Save your changes.
-4. Run `docsify serve docs`.
-<!-- markdown-link-check-disable-next-line -->
-5. Preview `https://kyma-project.io` in your browser on `http://localhost:3000`.
+> [!NOTE]
+> The `npm run docs:build` command copies all the unreferenced assets and non-graphical files (like scripts, documents, etc.) to the `docs/public` directory to include them in the `dist` folder of the project.