docs-mcp

= Redpanda Docs Site :url-docs: https://docs.redpanda.com :url-org: https://github.com/redpanda-data :url-gh-docs: {url-org}/documentation :url-ui: {url-org}/docs-ui :url-extensions: {url-org}/docs-extensions-and-macros :hide-uri-scheme: :url-contributing: ./meta-docs/CONTRIBUTING.adoc :url-netlify: https://netlify.com :url-netlify-docs: https://docs.netlify.com :url-antora-docs: https://docs.antora.org :url-redoc: https://github.com/Redocly/redoc :idprefix: :idseparator: - ifdef::env-github[] :important-caption: :exclamation: :note-caption: :paperclip: endif::[] :toc: :toc-title: Contents

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"]

++++

++++

This is the Antora playbook project (site build) for the Redpanda docs site published at {url-docs}.

== Playbook

The playbook, link:antora-playbook.yml[antora-playbook.yml]configures 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 {url-ui}[UI project], and the {url-extensions}[custom extensions].

image::images/antora.svg[]

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 link:{url-contributing}[Contributing guide].

== Content sources

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

=== Redpanda docs

Redpanda documentation is stored in versioned branches prefixed with v/. For more details, see the https://github.com/redpanda-data/documentation/blob/main/README.adoc[README].

=== API docs

The OpenAPI spec files are stored in the api/modules/ROOT/attachments/ directory of the {url-gh-docs}/tree/api[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 {url-ui}/blob/main/src/layouts/swagger.hbs[swagger UI layout] uses this attribute to render the OpenAPI docs using {url-redoc}[Redoc].

image::images/api.png[Preview of API docs]

=== Search page

The site-wide search page is hosted in the {url-gh-docs}/tree/site-search[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 link:{url-algolia}[Algolia] search index. The index is generated on each build of the production site using the {url-extensions}[Algolia indexer extension].

image::images/search.png[Preview of site search]

=== Shared content

The {url-gh-docs}/tree/shared[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 {url-extensions}[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 {url-extensions}[glossterm macro]. The content of these term page is also added automatically to reference:glossary.adoc pages by the {url-extensions}[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 {url-extensions}.

== Netlify configuration and redirects

The docs site is hosted on link:{url-netlify}[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.

NOTE: When you delete, rename, or move an existing page, use the {url-antora-docs}/antora/latest/page/page-aliases/[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 link:{url-netlify-docs}/configure-builds/file-based-configuration/[Netlify documentation].

== Contributing

To learn how to use the playbook and generate the docs site locally, see our link:{url-contributing}[contributing guide].