docs-site

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

++++
<p>
<a href="https://docs.redpanda.com">
<object type="image/svg+xml">
  <img src="https://raw.githubusercontent.com/redpanda-data/docs-ui/main/src/img/redpanda-docs-logo.svg"/>
</object>
</p></a>
++++

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 core docs

Redpanda core 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].

== 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].