Add new documentation to the website

​ This document explains how to render a new topic in the documentation on the Kyma website from various sources in repositories under kyma-project. It also describes how to modify an existing topic if you want OpenAPI specifications to show in a given topic's documentation.

Add a new documentation topic

Follow these steps:

  • Kyma repository
  • Other repositories

NOTE: Before merging your PR, you can check if the topic you added is rendered properly on the website thanks to docs-preview built on every PR.

Add a single OpenAPI specification

In addition to documentation, there are also OpenAPI specifications rendered on the Kyma website. You can find these specifications under the API Consoles type in the right navigation panel of a given documentation topic.

To add a new specification, follow these steps:

  • Kyma repository
  • Other repositories

NOTE: Before merging your PR, you can check if the specification you added is rendered properly on the website thanks to docs-preview built on every PR.

Add a new repository documentation

Follow these steps if you want the documentation from a repository under the kyma-project or kyma-incubator organization to be rendered on the website under the Docs view.

NOTE: Documents should follow the content strategy, have proper types, metadata, and numbering. See the Kyma docs for reference.

  1. Create the .kyma-project-io folder in the given repository and add appropriate documentation topics to this folder.

  2. Add the new entry in the docs field in config.json:

    Click to copy
    docs: {
    ...
    "{REPOSITORY_NAME}": {
    "displayName": "{DISPLAY_NAME}",
    "organization": "{ORGANIZATION_NAME}",
    "repository": "{REPOSITORY_NAME}",
    "branches": {BRANCHES},
    "lastReleases": {LAST_RELEASES},
    "navPath": "{NAV_PATH}",
    "rootPath": {
    "docsType": "{DOCS_TYPE}",
    "docsTopic": "{DOCS_TOPIC}"
    }
    }
    }

    where:

    • {REPOSITORY_NAME} is the name of the repository with documentation sources.
    • {DISPLAY_NAME} is the name you want to be visible under the Docs drop-down menu in the main navigation panel on the Kyma website.
    • {ORGANIZATION_NAME} is the name of the organization under which the repository sits. It can be either kyma-project or kyma-incubator.
    • {BRANCHES} are the names of branches that will be rendered. It should contain at least the main branch.
    • {LAST_RELEASES} is the number of the last release that will be rendered. If you only want to display branches, set the value to 0.
    • {NAV_PATH} is the URL path you want to assign to your docs entry under the Docs drop-down menu. For example, if you add CLI docs, specify cli as the path to be be redirected to https://kyma-project.io/docs/cli after selecting CLI from the Docs drop-down menu.
    • {DOCS_TYPE} is the document type that should be visible under the navigation path.
    • {DOCS_TOPIC} is the documentation topic that should be visible under the navigation path.

    See this example:

    Click to copy
    "{REPOSITORY_NAME}": {
    "displayName": "CLI",
    "organization": "kyma-project",
    "repository": "cli",
    "branches": ["main"],
    "lastReleases": 0,
    "navPath": "cli",
    "rootPath": {
    "docsType": "cli",
    "docsTopic": "overview"
    }
    }
  3. Create a PR, wait for the review, merge the changes, and wait for the website to be rebuilt. The new entry with the new documentation will appear under the Docs drop-down menu in the main navigation panel on the Kyma website.