Working on Documentation

This page describes how Apache Cassandra documentation is structured, how to preview changes locally, and how to submit documentation patches.

Documentation System

Cassandra documentation is authored in AsciiDoc and built with Antora.

Documentation source: doc/ directory in the apache/cassandra repository
Site generation and publish tooling: apache/cassandra-website repository
Module structure: doc/modules/cassandra/pages/ contains the main documentation pages
Navigation: Defined in doc/modules/cassandra/nav.adoc and doc/modules/ROOT/nav.adoc

Repository Layout

apache/cassandra/
└── doc/
    ├── antora.yml              # Antora component descriptor
    ├── modules/
    │   ├── cassandra/
    │   │   ├── nav.adoc        # Main navigation
    │   │   └── pages/          # Documentation pages
    │   └── ROOT/
    │       ├── nav.adoc        # Development pages navigation
    │       └── pages/          # Root-level pages
    └── scripts/                # Generated docs scripts

Local Preview

Use the official two-repo flow when you want to validate Cassandra docs the same way the website build will consume them:

# 1. Clone both repos
git clone https://github.com/apache/cassandra.git
git clone https://github.com/apache/cassandra-website.git

# 2. In apache/cassandra, make your doc edits and regenerate generated docs if needed
cd cassandra
ant gen-asciidoc

# 3. In apache/cassandra-website, follow the website README/run.sh flow
#    so the preview reads from your local Cassandra checkout
cd ../cassandra-website

# 4. Start the local preview
./run.sh website preview

# 5. Open the site and verify your page, nav, and xrefs
#    http://localhost:5151

For quick draft-only checks in this workzone, you can also use:

./build.sh build
./build.sh preview

That validates this draft site, but upstream-ready Cassandra doc validation still needs the cassandra-website preview flow. See the cassandra-website README for the exact website-side setup details.

Submitting Documentation Changes

Documentation changes follow the same contribution workflow as code changes:

Create a JIRA ticket (or find an existing one) for the documentation change
Make your changes in the doc/ directory of your Cassandra fork
Submit a pull request or attach a patch to the JIRA ticket
Tag the ticket with doc-impacting if it accompanies a code change

Writing Conventions

Use one = Title (H1) per page
Use == through ===== for subsections
Use [source,sql] for CQL code blocks, [source,yaml] for configuration, [source,bash] for shell commands
Use NOTE, TIP, IMPORTANT, WARNING, CAUTION admonition blocks
Use xref:page.adoc[Display Text] for cross-references within the documentation

This page covers the basics of documentation contribution. For comprehensive details on the Antora build system, generated documentation, and the publish pipeline, see Release and Publish and Generated Documentation.