redpanda-data/docs

= Redpanda Documentation :url-playbook: https://github.com/redpanda-data/docs-site

image:https://img.shields.io/badge/slack-purple[Slack, link="https://redpanda.com/slack"] image:https://img.shields.io/twitter/follow/redpandadata.svg?style=social&label=Follow[Twitter, link="https://twitter.com/intent/follow?screen_name=redpandadata"] image:https://api.netlify.com/api/v1/badges/5b89dd6f-1847-419c-b3be-a1650ce8992f/deploy-status[Netlify Status, link="https://app.netlify.com/sites/redpanda-documentation/deploys"] image:https://img.shields.io/coderabbit/prs/github/redpanda-data/docs?utm_source=oss&utm_medium=github&utm_campaign=redpanda-data%2Fdocs&labelColor=171717&color=FF570A&label=CodeRabbit+Reviews[CodeRabbit Reviews, link="https://coderabbit.ai"]

++++

++++

This repository hosts the documentation content for Redpanda Self-Managed.

== Contribute

The Redpanda docs are open source, and we welcome your contributions!

Before you add or edit content, consult the Redpanda https://github.com/redpanda-data/docs-site/blob/main/meta-docs/STYLE-GUIDE.adoc[Style Guide] for product documentation guidelines.

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

|=== |Option|Description

|<> |Suggest a change by opening an issue on GitHub.

|<> |Make changes directly to the documentation and submit them through a pull request.

|===

=== Open an issue

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

. Verify whether a similar issue already exists in that repository to avoid duplication. . 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 redpanda-data/documentation-private.

=== Contribute content

You have two options to contribute to the documentation:

. Directly edit a page on GitHub by selecting Make a contribution > Edit on GitHub located at the bottom of a documentation page. . Clone the docs repository to make changes locally on your machine. For a guide, see {url-playbook}/blob/main/meta-docs/CONTRIBUTING.adoc[Submit your first contribution].

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.

== Local development

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 Self-Managed. 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 Self-Managed. The main branch always contains docs for the latest release.

The production {url-playbook}[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 ....