Publishing the Documentation Site

This guide covers how to build and publish the Apache Tika documentation site.

Overview

The documentation is built using Antora, a static site generator for AsciiDoc. The site supports multiple versions through Git branches and includes client-side search powered by Lunr.

Prerequisites

  • Maven 3.9+

  • Git

  • Internet access on first build — the Antora plugin downloads Node.js into ~/.cache/tika-antora/ (~100 MB, one-time per machine; reused across clean builds and across worktrees)

Building the Site Locally

The docs module is only included in the reactor under the apache-release profile. Build the site from the repo root:

./mvnw package -Papache-release -pl :tika-docs -DskipTests

The generated site will be at docs/target/site/. The current git commit and date are stamped automatically onto the home page (a generated copy of the playbook lives at docs/antora-playbook-stamped.yml — gitignored).

The playbook is pinned in docs/pom.xml (<playbook>antora-playbook-stamped.yml</playbook>), so it cannot be overridden from the command line — an explicit POM value beats the plugin’s antora.playbook user property. To build against the unstamped playbook, change that element locally.

Previewing the Site

Option 1: Python HTTP server (recommended)

cd docs/target/site
python3 -m http.server 8000

Then open http://localhost:8000 in your browser.

Option 2: Node.js HTTP server

npx http-server docs/target/site -p 8000

Then open http://localhost:8000 in your browser.

Option 3: Open static HTML directly

# Linux
xdg-open docs/target/site/index.html

# macOS
open docs/target/site/index.html

# Windows
start docs/target/site/index.html
Opening static HTML directly may not fully test search and relative links.

Living documentation

docs/modules/ROOT/examples/ is entirely symlinks into module resources — mostly src/test/resources/config-examples/ across the parser, pipes-plugin, and serialization modules, plus a few src/test/resources/configs/ and tika-async-cli’s shipped `config-template.json. Nearly every published example is therefore a config the build actually exercises, and editing the source file updates the docs on the next build.

Never edit or de-symlink a file under examples/: fix the module’s resource instead.

Version Management

Documentation versions are managed through Git branches with the docs/ prefix.

Branch Structure

  • HEAD (main branch) — current development version (SNAPSHOT)

  • docs/X.Y.Z — one branch per released version, e.g. docs/4.0.0

The playbook (antora-playbook.yml) builds all docs/* branches automatically.

Publishing to the Site

Build the docs with Maven, then run publish-docs.sh to copy the output to a tika-site SVN checkout (with URL flattening so /docs/tika/X.Y.Z/…​ becomes /docs/X.Y.Z/…​):

./mvnw package -Papache-release -pl :tika-docs -DskipTests
cd docs
./publish-docs.sh /path/to/tika-site/publish

# Then in the SVN checkout:
cd /path/to/tika-site
svn add publish/docs publish/_ publish/search-index.js --force
svn commit -m "Publish 4.0.0-SNAPSHOT docs"

The Maven package step builds the Antora site (stamping the current git commit and date on the home page); publish-docs.sh copies the output to the site checkout with the correct directory layout:

  • publish/docs/4.0.0-SNAPSHOT/ — the documentation pages

  • publish/_/ — CSS, JS, fonts (shared across versions)

  • publish/docs/index.html — redirect to latest version

  • publish/search-index.js — the Lunr index, with URLs rewritten to /docs/…​ (TIKA-4743); it sits beside _/, not under docs/, and must be `svn add`ed on the first publish or search 404s

Publishing a Release

When releasing a new version (e.g., 4.0.0):

# 1. The release tag is the bare version (see the release guide, Step 12)

# 2. Create docs branch from the tag
git checkout -b docs/4.0.0 4.0.0

# 3. Update version in antora.yml
sed -i "s/4.0.0-SNAPSHOT/4.0.0/" docs/antora.yml
git commit -am "Set docs version to 4.0.0"
git push origin docs/4.0.0

# 4. Build and publish
./mvnw package -Papache-release -pl :tika-docs -DskipTests
cd docs
./publish-docs.sh /path/to/tika-site/publish

# 5. Commit to SVN
cd /path/to/tika-site
svn add publish/docs publish/_ publish/search-index.js --force
svn commit -m "Publish 4.0.0 docs"

Updating Released Documentation

To fix or update documentation for a released version:

# 1. Checkout the docs branch
git checkout docs/4.0.0

# 2. Make changes (docs or config examples)
# Edit files as needed...

# 3. Commit and push
git commit -am "Fix PDF parser example"
git push origin docs/4.0.0

# 4. Rebuild and republish
./mvnw package -Papache-release -pl :tika-docs -DskipTests
cd docs
./publish-docs.sh /path/to/tika-site/publish
cd /path/to/tika-site
svn commit -m "Update 4.0.0 docs"

Publishing the API docs (Javadoc)

The per-version API docs at https://tika.apache.org/<version>/api/ are a single aggregated Javadoc across all modules, generated from the release source tree and copied into the tika-site checkout next to the Antora docs.

Tika modules declare an Automatic-Module-Name but ship no module-info.java, so maven-javadoc-plugin’s aggregate goal defaults to a modular invocation that emits nothing (see TIKA-4318). `tika-parent works around this with an explicit <sourcepath> listing every module’s src/main/java (except tika-grpc). That list is hand-maintained, so run the check in step 2 before generating — a newly added module would otherwise drop out of the docs silently.

  1. Build and install first. javadoc:aggregate compiles nothing; it needs every module jar (and grpc’s generated sources) in the local repo. -Pfast skips tests for speed:

    ./mvnw clean install -Pfast

  2. Verify the aggregate <sourcepath> still covers every module:

    python3 .github/scripts/check_javadoc_sourcepath.py
# on failure it names the missing module(s); regenerate the list with --fix:
python3 .github/scripts/check_javadoc_sourcepath.py --fix

  3. Generate the aggregate Javadoc (output in target/reports/apidocs/; tika-grpc is intentionally excluded):

    ./mvnw javadoc:aggregate

  4. Copy it into the tika-site checkout as this version’s api/ directory and commit:

    mkdir -p /path/to/tika-site/publish/<version>
cp -r target/reports/apidocs /path/to/tika-site/publish/<version>/api
cd /path/to/tika-site
svn add publish/<version>
svn commit -m "Add <version> API docs"

Site Structure

The Antora configuration files:

  • docs/antora.yml - Component descriptor (name, version, navigation)

  • docs/antora-playbook.yml - Site-wide configuration (sources, UI, extensions)

  • docs/modules/ROOT/nav.adoc - Navigation sidebar structure

  • docs/modules/ROOT/pages/ - Documentation pages

  • docs/modules/ROOT/examples/ - Symlinks to config examples

  • docs/supplemental-ui/ - Custom UI components (header, footer, search)

Search

The site includes client-side search powered by the Lunr extension. The search index is generated at build time and requires no server-side infrastructure.

Logos

Official Apache Tika logos are archived at docs/assets/logos/asf-tika-logos.zip.