Skip to content

The Antora playbook project, contributing documentation, home page, search page, and API pages for the Redpanda docs site.

Notifications You must be signed in to change notification settings

redpanda-data/docs-site

Repository files navigation

Redpanda Docs Site

Slack Twitter Netlify Status

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.

antora

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.

Preview of API docs

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.

Preview of site search

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.

About

The Antora playbook project, contributing documentation, home page, search page, and API pages for the Redpanda docs site.

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published