Contribute to Redpanda Docs

Contents

• Introduction to Antora
• Choose a way to contribute
  • Open an issue
  • Contribute content
• Submit your first contribution
  • Prerequisites
  • Clone the Redpanda docs repository
  • Make your changes
  • Build and test your changes locally
  • Submit your changes
• Find content
  • Docs structure
• Mark a version as end of life
• Hide a component from the product selector
• Create index pages
• Move, delete, or rename pages
  • Use page aliases
  • Mark a page as removed
• Single-sourcing
  • Single-sourcing pages across repos
  • Single-sourcing content across repos
• Update the nav tree
  • Feature status badges
• Feature flag
• Manage and define categories
  • Central repository for categories
  • Contribute to category definitions
  • Guidelines for proposing categories
• Redpanda Labs
• Style guide
• Troubleshooting
  • Reference validation
• Contact us

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

Tip	For help with Asciidoc, see the Antora and Asciidoc playground. Or, see the Asciidoc syntax quick reference.

Introduction to Antora

Antora is a static site generator that facilitates a docs-as-code workflow. In Antora, documentation is stored in Git repositories and processed to output a static website.

Antora can collect files from a combination of local, remote public, and remote private repositories over any protocol supported by git.

Antora uses Asciidoctor.js to convert Asciidoc to HTML, then it uses Handlebars to set that HTML into a page layout.

The Handlebars templates and other frontend elements, such as CSS and JavaScript, are stored in a separate repository. The UI is served in a ui-bundle.zip file that is made available in GitHub release and referenced in the playbook.

Learn more about Antora in this introduction on YouTube.

Choose a way to contribute

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 GitHub issues to track, plan, and prioritize tasks. To suggest changes, you can create an issue, which the team will then evaluate:

1. Find the repository where the docs are hosted.

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

3. 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 Submit your first contribution.

If you’re looking for an open issue to fix, 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.

Submit your first contribution

This section helps you get started with your first contribution by running through the steps for making a change.

Prerequisites

To generate the site, you must have Node.js 16 or higher installed on your machine.

node --version

If this command fails, you don’t have Node.js installed.

We recommend using Visual Studio Code with the Asciidoc extension to edit documentation. The Asciidoc extension provides useful features such as folding conditionals and titles to make it easier to work with large documents.

Clone the Redpanda docs repository

Documentation is hosted in GitHub repositories. To work on the documentation repository, clone it on your local machine.

Tip	You can find all documentation repositories in the antora-playbook.yml file under content.sources. See Find content

1. Clone the repository, and check out the branch that you want to work on.

   git clone https://github.com/redpanda-data/docs
   cd docs

   ❗	If you’re not a Redpanda employee, you’ll need to fork the repository and work on your local fork instead.

   The default main branch contains the latest version of the Redpanda docs. To work on an older version check out the versioned branch. For example:

   git checkout v/22.3

2. Create a new branch for your changes.

   git checkout -b <branch-name>

Make your changes

After cloning the docs repository and checking out a new local branch, you’re ready to make your changes.

Tip	For help navigating a docs repository, see the Docs Structure section. For rules and recommendations as well as help with Asciidoc syntax, see the Redpanda documentation style guide.

Build and test your changes locally

When working on a docs project, you should build and preview the docs on your local machine to see your changes before going live.

The repository contains a script that watches Asciidoc files in the pages/ directories and antora.yml files in your local repository and triggers a new Antora build when it detects changes to those files. The script also starts a web server and can use LiveReload to reload the browser tab after the Antora build completes.

To use the script:

1. Install dependencies.

   npm install && npm update

2. If you’re using Chrome, install the LiveReload chrome extension.

3. Start the build.

   npm run start

   The build first generates the site then serves the files in the output directory using a local web server.

   The web server’s host URL is printed to the console after the watch task completes.

   The console output prints status information every time a change is detected.

   [17:33:59] Starting 'generate'...
   [17:34:02] Finished 'generate' after 3.35 s

4. Make changes to your AsciiDoc files locally. The browser tab should automatically reload after a short while.

5. Use Ctrl+C to stop the process.

Tip	If you don’t want to use the live reload script, you can build the site and serve its static contents using this command: npm run build npm run serve

Submit your changes

After making your changes, and testing how they look, you’re ready to submit them to GitHub for review.

1. Stage your changes for commit.

   git add <filenames>

2. Commit your changes.

   git commit -m "Concise message that describes your changes"

3. Push your local branch to the remote repository.

4. In the GitHub UI, open a pull request.

Thanks! We’ll review your changes and provide feedback and guidance as necessary.

Find content

All content served on the docs site is fetched from GitHub repositories listed under content.sources in the playbook.

For example:

content:
  sources:
  - url: https://github.com/redpanda-data/documentation (1)
    branches: [v/*, api, shared, site-search]

1. Clone this repository to work on Redpanda docs, the home page, shared content, the OpenAPI docs, or the site search.

Docs structure

All content sources are organized according to the same content hierarchy.

📒 repository (1)
  📄 antora.yml (2)
  📂 modules (3)
    📂 ROOT (4)
      📁 attachments (5)
      📁 examples (6)
      📁 images (7)
      📁 pages (8)
      📁 partials (9)
      📄 nav.adoc (10)
    📂 another-module (11)
      📁 pages
  📁 packages (12)

1. (Required) The repository root and the content source root. Antora assumes the content source root is at the root of a repository unless the start_path or start_paths key is assigned a value on a content source in the site’s playbook.

2. (Required) A component version descriptor file, named antora.yml, is required at each content source root. An antora.yml file indicates to Antora that the contents of a directory named modules/ should be collected and processed.

3. (Required) A modules/ directory must be located at the same hierarchical level as an antora.yml file in a content source root.

4. (Optional) Antora applies special behavior to the publishable resources in a ROOT module directory. ROOT is a reserved directory name and must be in all uppercase letters. A module directory must contain at least one family directory.

5. (Optional) Attachments family directory (reserved directory name).

6. (Optional) Examples family directory (reserved directory name).

7. (Optional) Images family directory (reserved directory name).

8. (Optional) Pages family directory (reserved directory name).

9. (Optional) Partials family directory (reserved directory name).

10. (Required) Nav tree file named nav.adoc.

11. (Optional) named module directory. You can create as many named module directories as you require. A module directory must contain at least one family directory.

12. Antora won’t process the files in this directory because it’s located outside the modules/ directory.

Tip	Learn more about the Antora structure in the docs: How to Organize Your Content Files.

Mark a version as end of life

When a version of the docs reaches end of life, you can mark it as such in the antora.yml file.

antora.yml

asciidoc:
  attributes:
    page-eol: true

When a component version includes this attribute, a banner is displayed at the top of the page to warn users that the version is no longer supported. A link to the latest version is provided.

Hide a component from the product selector

By default, Antora adds all components to the dropdown selector in the UI. If you don’t want a component to appear in the dropdown, add the page-exclude-from-dropdown-selector: true attribute to the antora.yml file of each component version.

antora.yml

asciidoc:
  attributes:
    page-exclude-from-dropdown-selector: true

For example, we use this attribute for the api component so that API is not displayed as a separate product in the component selector.

Create index pages

Index pages are docs topics that provide links to their top-level child topics in the nav tree.

For example:

* xref:get-started:index.adoc[Get Started] (1)
** xref:get-started:intro-to-events.adoc[Introduction to Redpanda]
** xref:get-started:architecture.adoc[How Redpanda Works]
** xref:get-started:licenses.adoc[Redpanda Licensing]
** xref:get-started:quick-start.adoc[Redpanda Quickstart]
** xref:get-started:rpk-install.adoc[Introduction to rpk]
** xref:get-started:code-examples.adoc[Build a Sample Application]

1. This page is an index. After the build, it will contain the titles and descriptions of all the topics underneath it.

To create an index page, give it a title and the page-layout: index attribute.

= Example Index Page
page-layout: index

The UI takes care of generating the links from the titles and description attributes on each child page.

Move, delete, or rename pages

If you move, delete, or rename pages, you must either:

• Redirect those page URLs to an existing page in the docs using the page-aliases attribute.

• Mark those pages as intentionally removed without an alias.

Warnings are logged to the console if any pages aren’t marked as intentionally removed or not included in a page alias. For example:

/23.1/deploy/deployment-option/cloud/provision-a-dedicated-cluster/ does not exist in 23.3
/23.2/upgrade/deprecated/cluster-resource/ does not exist in 23.3

Use page aliases

The page-aliases attribute is set in the page header of a target page using an attribute entry. The target page refers to the page you’re redirecting a source page to. The source page refers to the deleted, renamed, or moved page that you’re redirecting from. A source page’s resource ID (its resource ID before it was deleted, renamed, or moved) is assigned to the page-aliases attribute in a target page. Multiple resource IDs can be assigned to the attribute in a comma-separated list.

= Title of Target Page
:page-aliases: deleted-page-filename.adoc, renamed-page-filename.adoc

Antora calculates the URL for a source page’s resource ID and generates redirect information so that the source page URL redirects to the target page URL. Any coordinates, such as version or component, that aren’t specified in a resource ID assigned to page-aliases are interpolated from the target page’s coordinates. The generated output format of the redirect information is determined by your chosen redirect facility.

📎	A resource ID assigned to a page-aliases attribute can be used in an xref. Therefore, if you delete, rename, or move a page, you don’t need to update any references to it in your source files.

The content of the page-aliases attribute is used to create Netlify redirects in the _redirects file at build time.

❗	Make sure that links are relative to the current component version. Do not link to specific versions in page aliases.

Mark a page as removed

If you intentionally remove a page without a page alias, you can add it to the antora.yml file for the component version. For example:

asciidoc:
  attributes:
    removals-without-aliases:
      - page: upgrade/deprecated/cluster-resource/
        reason: The cluster resource was deprecated in version 23.2. We no longer need a page dedicated to migration in this version.

Single-sourcing

Practice the DRY (don’t repeat yourself) principle by single-sourcing repeated content. Common examples of single-sourced content include prerequisites, contact info, and foundational steps of how-to guides.

For single-sourcing content in different repositories, see Single-sourcing across repos.

For single-sourcing content in the same repository, put shared content in the partials/ directory. For details about partials, see Partials in the Antora docs.

📎	You can include partials inside other partials. You can also reference partials when single-sourcing across repos.

Inside partials, you can conditionally render content depending on attributes that are available on the page that you include them in.

For example:

ifndef::env-kubernetes[]
This will be rendered only if the pages you include the partial in do not have the `env-kubernetes` attribute.
endif::[]

ifdef::env-kubernetes[]
This will be rendered only if the pages you include the partial in have the `env-kubernetes` attribute.
endif::[]

If you need to link to different pages in partials depending on the context of the page that you include them in, you can define attributes at the top of the page to hold the links. For example:

ifdef::env-kubernetes[]
:data-archiving-link: manage:kubernetes/data-archiving.adoc
endif::[]
ifndef::env-kubernetes[]
:data-archiving-link: manage:data-archiving.adoc
endif::[]

To learn more, see xref:{data-archiving-link}[Data Archiving]

Single-sourcing pages across repos

Redpanda documentation sits in different repositories for Self-Managed, Cloud, Redpanda Connect, and Labs. (See Find content.)

To single-source pages across repos:

1. In the source repository, wrap the single-sourced page, after the title and aliases, with // tag::single-source[].

2. In the other repository, add the content with an include directive and the single-source tag. For example:

   include::ROOT:get-started:partner-integration.adoc[tag=single-source]

   For more information about the include directive, see the Asciidoc docs.

For an example of a page single-sourced from the docs repo into the cloud-docs repo, see docs.redpanda.com/current/get-started/partner-integration/ and docs.redpanda.com/redpanda-cloud/get-started/partner-integration/.

The file source in the docs repo looks like this:

= Partner Integrations
:page-aliases: reference:partner-integration.adoc
// tag::single-source[]
:description: Learn about Redpanda integrations built and supported by our partners.

Learn about Redpanda integrations built and supported by our partners.

[.no-clip]
[cols="1a,2a,1a"]
|===
|*Partner* |*Description* |*More information*
...

// end::single-source[]

The shared version of this page in the cloud-docs repo looks like this:

= Partner Integrations
include::ROOT:get-started:partner-integration.adoc[tag=single-source]

Single-sourcing pages across repos usually requires two PRs (one for each repo) as well as conditionals. For example:

* xref:get-started:rpk-install.adoc[]
* xref:get-started:config-rpk-profile.adoc[]
// This topic is not available in our Cloud docs.
ifndef::env-cloud[]
* xref:get-started:rpk-quickstart.adoc[]
endif::[]

Single-sourcing content across repos

To single source certain content:

1. In the source repository, wrap the single-sourced content with a tag.

2. In the other repository, add the tag in an include directive.

For example, in the cluster-properties.adoc source file in the docs repo, add:

// tag::audit_excluded_principals[]
=== audit_excluded_principals

List of user principals to exclude from auditing.

*Requires restart:* No

*Visibility:* `user`

*Type:* array

*Default:* `null`

---

// end::audit_excluded_principals[]

In the cloud-docs file where you want to add this shared content, add an include directive:

include::ROOT:reference:properties/cluster-properties.adoc[tags=audit_excluded_principals]

Update the nav tree

All doc repositories use a single navigation file for the nav tree, which is defined in the nav.adoc file of the ROOT module.

To update the nav tree, edit the nav.adoc file.

For more information about navigation files, see the Antora docs.

Feature status badges

Documentation pages can display status badges to communicate the maturity and availability of features to users. The badges appear in three locations: the main content area, the table of contents (TOC), and the left navigation tree.

Beta features

In cloud-docs, and occasionally in other repos, individual features can exist in beta status. Beta features are available for testing and feedback but are not supported by Redpanda and should not be used in production environments.

To mark a page as beta, add the page-beta attribute to your page header:

= Your Page Title
:page-beta: true

This displays a blue "beta" badge on the page with the tooltip text: "{page-beta-text}"

Limited availability features

Some features have limited availability and require contacting Redpanda for access. These features are typically in early access programs or require special licensing.

To mark a page as limited availability, add the page-limited-availability attribute to your page header:

= Your Page Title
:page-limited-availability: true

This displays a "Limited Availability" pill-shaped badge on the page with the tooltip text: "{page-limited-availability-text}"

Badge appearance

Both badges appear in:

• Main content area: Below the page title

• TOC: In the sticky navigation that appears when scrolling

• Left navigation: Next to the page title in the navigation tree

  • Beta: Displays as (beta) text

  • Limited Availability: Displays as an orange pill badge

📎	You should only use one status badge per page. Do not combine page-beta and page-limited-availability on the same page.

Feature flag

If a feature is marked as a feature flag, please include the partial admonition that identifies it. To include the admonition, add include::shared:partial$feature-flag.adoc[] to the top of the page after the title and any attributes.

Manage and define categories

Documentation categories are a crucial part of organizing content in a way that is intuitive and accessible to users. Categories ensure consistency across the Redpanda docs and labs, facilitating easier navigation and a better understanding of the content structure.

Central repository for categories

The categories for Redpanda docs are centrally managed in a YAML file located in the Redpanda docs repository.

This centralized approach allows the documentation team to maintain a coherent structure across all documentation, ensuring that every topic is appropriately categorized.

Contribute to category definitions

The Redpanda doc team welcomes contributions and suggestions for improving or expanding the category definitions. If you have ideas for new categories or adjustments to existing ones that could enhance the organization and discoverability of content, we encourage you to contribute in the following ways:

1. Open a pull request.

   If you’re familiar with the structure of the YAML file and have a specific change in mind, the most direct way to propose a category update is by opening a pull request against the valid-categories.yml file. Include a brief explanation of your proposed changes and how they improve the documentation structure.

2. Create an issue.

   If you’re less comfortable making direct changes or if your suggestion requires broader discussion, you can open an issue in the private Redpanda docs repository. In your issue, describe the proposed category addition or modification, providing context on why the change is beneficial and how it fits within the overall documentation strategy.

Guidelines for proposing categories

When suggesting new categories or modifications to existing ones, consider the following guidelines to ensure your proposal aligns with the documentation goals:

• Relevance: Categories should be directly relevant to Redpanda and its ecosystem, reflecting topics that users are likely to search for.

• Clarity: Category names and definitions should be clear and self-explanatory, avoiding jargon where possible.

• Consistency: Proposals should maintain consistency with existing categories, fitting logically within the overall structure.

• Breadth vs depth: Aim for categories that are broad enough to encompass multiple related topics but specific enough to be meaningful and useful for navigation.

Redpanda Labs

To contribute to Redpanda Labs, see the Redpanda Labs contribution guide.

Style guide

For rules and recommendations as well as help with Asciidoc syntax, see the Redpanda docs style guide.

Troubleshooting

Reference validation

Reference validation, which covers xrefs, includes, and images, is performed automatically when Antora runs. The validation errors will be shown in the log output.

If your build includes reference violations, such as broken xrefs, a report of those violations is printed to the terminal or CI log. Here’s an excerpt from that report:

[13:41:05.047] ERROR (asciidoctor): target of xref not found: redpanda:how-redpanda-works.adoc
    file: modules/get-started/pages/architecture.adoc
    source: https://github.com/redpanda-data/documentation (branch: v/22.3)

Each message shows the repository source, the refname, and the path from the root of that repository.

Contact us

Get in touch with the Redpanda docs team on Slack in the #docs channel.