- Introduction to Antora
- Choose a way to contribute
- Submit your first contribution
- Find content
- Mark a version as end of life
- Hide a component from the product selector
- Create index pages
- Move, delete, or rename pages
- Single-sourcing
- Update the nav tree
- Cloud pages
- Feature flag
- Manage and define categories
- Redpanda Labs
- Style guide
- Troubleshooting
- 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. |
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.
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. |
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:
-
Find the repository where the docs are hosted.
-
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 the redpanda-data/documentation-private repo.
|
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 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.
This section helps you get started with your first contribution by running through the steps for making a change.
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.
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
|
-
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
-
Create a new branch for your changes.
git checkout -b <branch-name>
After cloning the docs repository and checking out a new local branch, you’re ready to make your changes.
Tip
|
|
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:
-
Install dependencies.
npm install && npm update
-
If you’re using Chrome, install the LiveReload chrome extension.
-
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
-
Make changes to your AsciiDoc files locally. The browser tab should automatically reload after a short while.
-
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 |
After making your changes, and testing how they look, you’re ready to submit them to GitHub for review.
-
Stage your changes for commit.
git add <filenames>
-
Commit your changes.
git commit -m "Concise message that describes your changes"
-
Push your local branch to the remote repository.
-
In the GitHub UI, open a pull request.
Thanks! We’ll review your changes and provide feedback and guidance as necessary.
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]
-
Clone this repository to work on Redpanda docs, the home page, shared content, the OpenAPI docs, or the site search.
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)
-
(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
orstart_paths
key is assigned a value on a content source in the site’s playbook. -
(Required) A component version descriptor file, named
antora.yml
, is required at each content source root. Anantora.yml
file indicates to Antora that the contents of a directory namedmodules/
should be collected and processed. -
(Required) A
modules/
directory must be located at the same hierarchical level as anantora.yml
file in a content source root. -
(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.
-
(Optional) Attachments family directory (reserved directory name).
-
(Optional) Examples family directory (reserved directory name).
-
(Optional) Images family directory (reserved directory name).
-
(Optional) Pages family directory (reserved directory name).
-
(Optional) Partials family directory (reserved directory name).
-
(Required) Nav tree file named
nav.adoc
. -
(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.
-
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. |
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.
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.
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]
-
This page is an index. After the build, it will contains 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.
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
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 are 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. |
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.
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.
Antora supports single-sourcing Asciidoc files that are located in the partials/
directory. For details about partials, see Partials in the Antora docs.
📎
|
You can include partials inside other partials. |
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 has 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]
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.
Redpanda Cloud pages should be tagged accordingly. If you create a Redpanda Cloud page make sure to add the attribute page-cloud:true
to the top of the file under the title.
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.
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.
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.
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:
-
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. -
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.
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.
To contribute to Redpanda Labs, see the Redpanda Labs contribution guide.
For rules and recommendations as well as help with Asciidoc syntax, see the Redpanda docs style guide.
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.
Get in touch with the Redpanda docs team on Slack in the #docs channel.