Redpanda Docs Site

Contents

• Playbook
• Content sources
  • Redpanda docs
  • API docs
  • Search page
  • Shared content
• Extensions and macros
• Netlify configuration and redirects
• Contributing

This is the Antora playbook project (site build) for the Redpanda docs site published at docs.redpanda.com.

Playbook

The playbook, antora-playbook.ymlconfigures the production build for the docs site. This playbook tells Antora what documentation to assemble, where to find it, and what UI to apply to it.

The documentation is hosted in a separate Git repository, as is the UI project, and the custom extensions.

The production site is built for each change to the main branch. A deploy preview of the site is also published for each pull request.

Tip	For an introduction to Antora and helpful tips for getting started with local development, see the Contributing guide.

Content sources

The playbook pulls content from branches in the github.com/redpanda-data/documentation repository.

Redpanda docs

Redpanda documentation is stored in versioned branches prefixed with v/. For more details, see the README.

API docs

The OpenAPI spec files are stored in the api/modules/ROOT/attachments/ directory of the api branch.

The API component hosts all OpenAPI docs at the root of the site under the /api path.

The Asciidoc pages reference these attachments in the page-api-spec-url attribute. The swagger UI layout uses this attribute to render the OpenAPI docs using Redoc.

Search page

The site-wide search page is hosted in the site-search branch and is configured as a dedicated component called search so that we can host it at the root of the site under the /search path.

Search is powered by an Algolia search index. The index is generated on each build of the production site using the Algolia indexer extension.

Shared content

The shared branch contains content that is intended to be shared across all component versions.

The attributes in the ROOT/partials/attributes.yaml file are merged into the antora.yml file of each component version by the global attributes extension. These global attributes are required for all local builds as well as the production build.

The pages in the terms/partials/ directory are terms that can be referenced in any component version using the glossterm macro. The content of these term page is also added automatically to reference:glossary.adoc pages by the aggregate terms extension.

Extensions and macros

The Redpanda docs site includes custom extensions and macros to enhance the site and provide custom features.

For details about all the extensions and macros, see github.com/redpanda-data/docs-extensions-and-macros.

Netlify configuration and redirects

The docs site is hosted on Netlify.

The Netlify build is configured in the netlify.toml file. The redirects in this file redirect users from the previous Docusaurus URLs to the new Antora ones.

📎	When you delete, rename, or move an existing page, use the page-aliases attribute. Do not use the netlify.toml file. The redirects in this file must be bulk URL redirects, such as removing or renaming a component or component version.

For details about this file, see the Netlify documentation.

Contributing

To learn how to use the playbook and generate the docs site locally, see our contributing guide.