Redpanda Documentation

This repository hosts the documentation content for Redpanda Streaming.

Contribute

This repository is private, so you need write permissions to contribute content.

Before you add or edit content, consult the Redpanda Style Guide for product documentation guidelines.

To contribute to the Redpanda docs, you have the following options:

Option	Description
Open an issue	Suggest a change by opening an issue on GitHub.
Contribute content	Make changes directly to the documentation and submit them through a pull request.

Open an issue

The Redpanda docs team uses Jira to track, plan, and prioritize tasks. To suggest changes, you can create a GitHub issue, which the team will then evaluate:

1. Verify whether a similar issue already exists in that repository to avoid duplication.

2. Go to Issues > New Issue to create a new issue.

You have the option to assign the issue to yourself or leave the assignee field blank. The Redpanda docs team triages all new issues and will allocate a writer if one isn’t already assigned.

If you are a Redpanda employee, submit doc issues in Jira.

Contribute content

You have two options to contribute to the documentation:

1. Directly edit a page on GitHub by selecting Make a contribution > Edit on GitHub located at the bottom of a documentation page.

2. Clone the docs repository to make changes locally on your machine. For a guide, see Build and test your changes locally.

Check the open docs issues. If you find an issue you’d like to work on:

• If the issue is already assigned to someone else, please consider another one.

• If the issue is unassigned, add a comment expressing your interest in working on it.

Set up GitHub authentication

The Antora playbook in this repository fetches content from other GitHub repositories, including the private cloud-docs and rp-connect-docs repositories and this repository’s own versioned branches, so building the site requires a GitHub token, even for read-only builds.

Important

Antora does not use git credential helpers (such as the gh CLI helper or the macOS keychain), so you must complete this step even if git clone already works on your machine. By default, Antora reads credentials from the GIT_CREDENTIALS environment variable or the ~/.git-credentials file (with a fallback to $XDG_CONFIG_HOME/git/credentials).

If you aren’t already signed in to the GitHub CLI, run gh auth login first. Then store credentials one time:

echo "https://$(gh auth token):@github.com" >> ~/.git-credentials
chmod 600 ~/.git-credentials

If you don’t use the GitHub CLI, create a fine-grained personal access token: select redpanda-data as the resource owner, grant the token access to the private doc repositories, and set the Contents permission to read-only. Use the token in place of $(gh auth token). Organization approval may be required before the token becomes active.

Note	Tokens from gh auth token rotate when you sign in to the GitHub CLI again. If Antora builds start failing with 401 or 404 errors on remote content sources, remove the stale github.com line from ~/.git-credentials and re-run the setup command.

Local development

Local builds require the GitHub authentication set up above.

If you want to run the website locally, install and update the packages:

npm update

Then, build the docs and start a local web server:

npm run start

This command opens a browser window. Most changes are reflected live without having to restart the server.

Build the site

To build the files, run:

npm run build

This command generates static content in the docs directory and can be served using any hosting service.

You can serve the static files on a local web server using:

npm run serve

Versioning

Versioned content is stored in branches that track the version of Redpanda Streaming. Production branches use the v/x.y naming pattern. For example, branch v/22.3 hosts the content for version 22.3.x of Redpanda Streaming. The main branch always contains docs for the latest release.

The production docs site playbook instructs Antora to automatically aggregate content in the following branches:

• main: Content for the latest version of Redpanda.

• v/*: Content for previous versions of Redpanda.

• shared: Content that is shared across all versions (asciidoc attributes and terms)

• api: API docs as well as the source OpenAPI spec files.

• site-search: The global site search page.

Repository Structure

The documentation content is stored in the modules/ directory, where each module represents a top-level label in the documentation nav tree.

Each module has a pages/ directory that stores the documentation pages in Asciidoc format. Some modules also include a partials/ directory that contains single-sourced documentation that can be shared and referenced by any documentation pages across any module.

The shared module stores the images, attachments, and partials that do not belong to a single module and can be referenced by any documentation pages across any module.

modules/shared
├── attachments
├── images
└── partials