# Enable Topic Documentation in Redpanda Console

> For the complete documentation index, see [llms.txt](https://docs.redpanda.com/llms.txt). Component-specific: [streaming-full.txt](https://docs.redpanda.com/streaming-full.txt)

---
title: Enable Topic Documentation in Redpanda Console
latest-redpanda-tag: v26.1.9
latest-console-tag: v3.7.3
latest-operator-version: v26.1.4
# EOL = End-of-Life (support lifecycle status)
page-is-nearing-eol: "false"
page-is-past-eol: "false"
page-eol-date: March 31, 2027
latest-connect-version: 4.93.0
docname: config/topic-documentation
page-component-name: streaming
page-version: "26.1"
page-component-version: "26.1"
page-component-title: Streaming
page-relative-src-path: config/topic-documentation.adoc
page-edit-url: https://github.com/redpanda-data/docs/edit/main/modules/console/pages/config/topic-documentation.adoc
description: Learn how to embed your Kafka topic documentation into the Redpanda Console UI by linking a Git repository that contains the topic documentation files.
page-git-created-date: "2024-09-11"
page-git-modified-date: "2026-05-26"
support-status: supported
---

<!-- Source: https://docs.redpanda.com/streaming/current/console/config/topic-documentation.md -->

You can embed topic documentation into the Redpanda Console user interface by providing access to a public or private Git repository that hosts the documentation files in Markdown format.

![topic documentation](https://docs.redpanda.com/streaming/current/console/_images/topic-documentation.png)

Redpanda Console clones the provided Git repository and stores all Markdown files it finds in memory. The **Documentation** tab in the frontend displays the content of the Markdown file that matches the name of the Kafka topic.

| Path/Filename | Topic Name | Matches |
| --- | --- | --- |
| ordersv2.md | orders-v2 | ✗ |
| Orders-v2.md | orders-v2 | ✗ |
| orders-v2.md | orders-v2 | ✓ |
| /orders/orders-v2.md | orders-v2 | ✓ |

## [](#repository-information)Repository information

Start by specifying the Git repository that contains the Markdown documentation files. Provide the repository URL, the branch, and the base directory that contains the documentation.

### Standalone

```yaml
console:
  topicDocumentation:
    git:
      enabled: true
      repository:
        url: https://github.com/<github-organization>/<repository-name>.git
        branch: <branch-name>
        baseDirectory: <base-directory-path>
```

### Kubernetes embedded

When Redpanda Console is part of the Redpanda Helm chart or Operator:
#### Operator

```yaml
apiVersion: cluster.redpanda.com/v1alpha2
kind: Console
metadata:
  name: redpanda-console
spec:
  clusterRef:
    name: redpanda
  config:
    console:
      topicDocumentation:
        git:
          enabled: true
          repository:
            url: https://github.com/<github-organization>/<repository-name>.git
            branch: <branch-name>
            baseDirectory: <base-directory-path>
```

#### Helm

```yaml
console:
  enabled: true
  console:
    config:
      console:
        topicDocumentation:
          git:
            enabled: true
            repository:
              url: https://github.com/<github-organization>/<repository-name>.git
              branch: <branch-name>
              baseDirectory: <base-directory-path>
```

### Kubernetes standalone

When using the standalone Redpanda Console Helm chart:

```yaml
config:
  console:
    topicDocumentation:
      git:
        enabled: true
        repository:
          url: https://github.com/<github-organization>/<repository-name>.git
          branch: <branch-name>
          baseDirectory: <base-directory-path>
```

## [](#refresh-interval)Refresh interval

Define how often Redpanda Console should refresh the documentation from the repository.

```yaml
console:
  topicDocumentation:
    git:
      enabled: true
      refreshInterval: 10m
```

-   `refreshInterval`: Set a duration like `10m` to refresh documentation every 10 minutes. Use `0` to disable automatic refresh.


## [](#authenticate-with-private-git-repositories)Authenticate with private Git repositories

If the Git repository is private, Redpanda Console must authenticate using either:

-   A [GitHub Personal Access Token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) (PAT) over HTTPS (basic auth)

-   An [SSH private key](https://docs.github.com/en/authentication/connecting-to-github-with-ssh)


### [](#authenticate-using-a-github-personal-access-token-pat)Authenticate using a GitHub Personal Access Token (PAT)

#### Standalone

1.  Set the environment variables:

    ```bash
    TOPICDOCUMENTATION_GIT_BASICAUTH_USERNAME=token
    TOPICDOCUMENTATION_GIT_BASICAUTH_PASSWORD=<github_pat>
    ```

    Replace `<github_pat>` with a GitHub personal access token that has `repo` scope.

2.  Configure Redpanda Console:

    ```yaml
    console:
      topicDocumentation:
        git:
          enabled: true
          repository:
            url: https://github.com/<github-organization>/<repository-name>.git
            branch: <branch-name>
            baseDirectory: <base-directory-path>
          refreshInterval: 10m
          basicAuth:
            enabled: true
    ```

#### Kubernetes embedded

1.  Create the Secret:

    ```yaml
    apiVersion: v1
    kind: Secret
    metadata:
      name: topic-doc-git-auth
      namespace: redpanda
    type: Opaque
    stringData:
      TOPICDOCUMENTATION_GIT_BASICAUTH_PASSWORD: <github_pat>
    ```

2.  Configure the deployment:
##### Operator

```yaml
apiVersion: cluster.redpanda.com/v1alpha2
kind: Console
metadata:
  name: redpanda-console
spec:
  clusterRef:
    name: redpanda
  extraEnv:
    - name: TOPICDOCUMENTATION_GIT_BASICAUTH_USERNAME
      value: token
  extraEnvFrom:
    - secretRef:
        name: topic-doc-git-auth
  config:
    console:
      topicDocumentation:
        git:
          enabled: true
          repository:
            url: https://github.com/<github-organization>/<repository-name>.git
            branch: <branch-name>
            baseDirectory: <base-directory-path>
          refreshInterval: 10m
          basicAuth:
            enabled: true
```

##### Helm

```yaml
console:
  enabled: true
  extraEnv:
    - name: TOPICDOCUMENTATION_GIT_BASICAUTH_USERNAME
      value: token
  extraEnvFrom:
    - secretRef:
        name: topic-doc-git-auth
  console:
    config:
      console:
        topicDocumentation:
          git:
            enabled: true
            repository:
              url: https://github.com/<github-organization>/<repository-name>.git
              branch: <branch-name>
              baseDirectory: <base-directory-path>
            refreshInterval: 10m
            basicAuth:
              enabled: true
```

#### Kubernetes standalone

1.  Create the Secret:

    ```yaml
    apiVersion: v1
    kind: Secret
    metadata:
      name: topic-doc-git-auth
      namespace: redpanda
    type: Opaque
    stringData:
      TOPICDOCUMENTATION_GIT_BASICAUTH_PASSWORD: <github_pat>
    ```

2.  Reference it in Helm values:

    ```yaml
    config:
      console:
        topicDocumentation:
          git:
            enabled: true
            repository:
              url: https://github.com/<github-organization>/<repository-name>.git
              branch: <branch-name>
              baseDirectory: <base-directory-path>
            refreshInterval: 10m
            basicAuth:
              enabled: true

    extraEnv:
      - name: TOPICDOCUMENTATION_GIT_BASICAUTH_USERNAME
        value: token

    extraEnvFrom:
      - secretRef:
          name: topic-doc-git-auth
    ```

### [](#authenticate-using-ssh)Authenticate using SSH

#### Standalone

1.  Save the SSH key to a secure path (for example, `/etc/redpanda/ssh/id_rsa`).

2.  Set the environment variables:

    ```bash
    TOPICDOCUMENTATION_GIT_SSH_ENABLED=true
    TOPICDOCUMENTATION_GIT_SSH_USERNAME=git
    TOPICDOCUMENTATION_GIT_SSH_PRIVATEKEYFILEPATH=/etc/redpanda/ssh/id_rsa
    TOPICDOCUMENTATION_GIT_SSH_PASSPHRASE=<private-key-passphrase>
    ```

3.  Configure Redpanda Console:

    ```yaml
    console:
      topicDocumentation:
        git:
          enabled: true
          repository:
            url: git@github.com:<github-organization>/<repository-name>.git
            branch: <branch-name>
            baseDirectory: <base-directory-path>
          refreshInterval: 10m
          ssh:
            enabled: true
    ```

#### Kubernetes embedded

1.  Create the Secret:

    ```yaml
    apiVersion: v1
    kind: Secret
    metadata:
      name: topic-doc-git-ssh
      namespace: redpanda
    type: Opaque
    stringData:
      privateKey: |
        -----BEGIN OPENSSH PRIVATE KEY-----
        <ssh-private-key>
        -----END OPENSSH PRIVATE KEY-----
      passphrase: <private-key-passphrase>
    ```

2.  Mount the secret and set environment variables:
##### Operator

```yaml
apiVersion: cluster.redpanda.com/v1alpha2
kind: Console
metadata:
  name: redpanda-console
spec:
  clusterRef:
    name: redpanda
  extraVolumeMounts:
    - name: git-ssh
      mountPath: /etc/git-ssh
      readOnly: true
  extraVolumes:
    - name: git-ssh
      secret:
        secretName: topic-doc-git-ssh
  extraEnv:
    - name: TOPICDOCUMENTATION_GIT_SSH_ENABLED
      value: "true"
    - name: TOPICDOCUMENTATION_GIT_SSH_USERNAME
      value: git
    - name: TOPICDOCUMENTATION_GIT_SSH_PRIVATEKEYFILEPATH
      value: /etc/git-ssh/privateKey
    - name: TOPICDOCUMENTATION_GIT_SSH_PASSPHRASE
      value: <private-key-passphrase>
```

##### Helm

```yaml
console:
  enabled: true
  extraVolumeMounts:
    - name: git-ssh
      mountPath: /etc/git-ssh
      readOnly: true
  extraVolumes:
    - name: git-ssh
      secret:
        secretName: topic-doc-git-ssh
  extraEnv:
    - name: TOPICDOCUMENTATION_GIT_SSH_ENABLED
      value: "true"
    - name: TOPICDOCUMENTATION_GIT_SSH_USERNAME
      value: git
    - name: TOPICDOCUMENTATION_GIT_SSH_PRIVATEKEYFILEPATH
      value: /etc/git-ssh/privateKey
    - name: TOPICDOCUMENTATION_GIT_SSH_PASSPHRASE
      value: <private-key-passphrase>
```

#### Kubernetes standalone

1.  Create the Secret:

    ```yaml
    apiVersion: v1
    kind: Secret
    metadata:
      name: topic-doc-git-ssh
      namespace: redpanda
    type: Opaque
    stringData:
      privateKey: |
        -----BEGIN OPENSSH PRIVATE KEY-----
        <ssh-private-key>
        -----END OPENSSH PRIVATE KEY-----
      passphrase: <private-key-passphrase>
    ```

2.  Configure Helm values:

    ```yaml
    config:
      console:
        topicDocumentation:
          git:
            enabled: true
            repository:
              url: git@github.com:<github-organization>/<repository-name>.git
              branch: <branch-name>
              baseDirectory: <base-directory-path>
            refreshInterval: 10m
            ssh:
              enabled: true

    extraVolumeMounts:
      - name: git-ssh
        mountPath: /etc/git-ssh
        readOnly: true

    extraVolumes:
      - name: git-ssh
        secret:
          secretName: topic-doc-git-ssh

    extraEnv:
      - name: TOPICDOCUMENTATION_GIT_SSH_ENABLED
        value: "true"
      - name: TOPICDOCUMENTATION_GIT_SSH_USERNAME
        value: git
      - name: TOPICDOCUMENTATION_GIT_SSH_PRIVATEKEYFILEPATH
        value: /etc/git-ssh/privateKey
      - name: TOPICDOCUMENTATION_GIT_SSH_PASSPHRASE
        value: <private-key-passphrase>
    ```

Replace the following values throughout the examples:

-   `<github-organization>`: GitHub organization or user that owns the repository

-   `<repository-name>`: Name of the GitHub repository containing the topic documentation files

-   `<branch-name>`: Name of the Git branch to use (for example, `main` or `docs`)

-   `<base-directory-path>`: Relative path inside the repository where Markdown documentation files are stored

-   `<github_pat>`: GitHub personal access token with `repo` scope (used for basic authentication)

-   `<ssh-private-key>`: SSH private key content used to authenticate to GitHub (must be base64-safe if stored in secrets)

-   `<private-key-passphrase>`: Passphrase used to decrypt the SSH private key, if applicable


## [](#example-configuration)Example configuration

This example is for a setup where documentation needs frequent updates and is stored in a private repository accessed through SSH:

```yaml
console:
  topicDocumentation:
    enabled: true
    git:
      enabled: true
      repository:
        url: https://github.com/example/redpanda-docs
        branch: main
        baseDirectory: path/to/documentation
      refreshInterval: 10m
      ssh:
        enabled: true
        username: git
        privateKeyFilepath: "/home/user/.ssh/redpanda_docs_key"
        passphrase: "passphrase"
```

This configuration is designed for a secure and automated integration of topic documentation into the Redpanda Console, using SSH for secure repository access and a refresh interval that keeps the documentation consistently updated without manual intervention.