# Building Docs

> How to build, preview, and verify Quarkus documentation locally: root Maven build, docs rebuild, Roq dev server preview.

- Skill: `quarkusio/building-docs` (Agent Skill)
- Install (CLI): `npx skillmds@latest add quarkusio/building-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/quarkusio/building-docs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: quarkusio (https://skillmd.com/u/quarkusio)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/quarkusio/building-docs

---


# Building Documentation

## Supported Platforms

This workflow is supported on Linux, macOS, and Windows through WSL2.
Native Windows shells (PowerShell, CMD, Git Bash) are not supported.
Java 21+ is required. The repository includes a `./mvnw` wrapper — no
separate Maven install is needed.

## Quick Start

Run the full pipeline in one command:

```bash
just docs-preview
```

## How It Works

The script uses local marker files to keep the preview workflow fast:

* `docs/.docs-preview-root-build-last-run` — last successful root build.
  Used to decide whether Step 1 can be skipped.
* `docs/.docs-preview-root-build-head` — Git HEAD at last root build.
  Detects branch switches, checkouts, and pulls.
* `docs/.docs-preview-docs-build-last-run` — last successful docs rebuild.
  Used to decide whether Step 2 can be skipped.
* `docs/.docs-preview-last-run` — last preview run.
  Used to detect recently changed files and open the right preview URL.
* `docs/.docs-preview-times` — cached execution times for progress estimates.

All marker files are gitignored. Delete them to force a full rebuild.

**Caveat:** The script detects changes to docs sources and `pom.xml` files,
but does not detect uncommitted changes outside `docs/` (e.g., new config
properties, extension metadata, or generated-doc producers). If you modify
code that affects generated documentation, force a root build manually:
`QUARKUS_DOCS_PREVIEW_FULL=1 just docs-preview`

## Step 0 — Environment Setup

Source `detect-env.sh` to set `$MVN_THREADS`, `$MAVEN_OPTS`, and
`$BROWSER_CMD`:

```bash
. docs/detect-env.sh
```

The script computes Maven heap, thread count, and browser automatically
based on your machine.

## Step 1 — Root Build (from repo root)

Run **once**, then re-run roughly once a week, after pulling significant
upstream changes, or when Step 2 fails.

Use **`-DquicklyDocs`**, not **`-Dquickly`** (which sets `skipDocs=true`).
The extra flags are not covered by the profile and are needed to skip
integration-test modules, Gradle plugin build, and javadoc generation.

```bash
./mvnw $MVN_THREADS clean install -DquicklyDocs \
  -Dno-test-modules -Dskip.gradle.build=true -Dmaven.javadoc.skip=true
```

Fallback (single-threaded) if the parallel build fails:

```bash
./mvnw clean install -DquicklyDocs \
  -Dno-test-modules -Dskip.gradle.build=true -Dmaven.javadoc.skip=true
```

## Step 2 — Quick Docs Rebuild (from `docs/`)

```bash
cd docs
../mvnw -ntp package -Dasciidoctor.fail-if=ERROR    # quick rebuild (~1 min)
../mvnw -ntp clean package -Dasciidoctor.fail-if=ERROR  # if output looks stale
```

The `-Dasciidoctor.fail-if=ERROR` override lets the build succeed despite
AsciiDoctor warnings (the default `WARN` level fails on cross-reference
or attribute warnings that are harmless for local preview).

## Step 3 — Sync (from `docs/`)

First time: `./sync-web-site.sh`

Subsequent iterations — fast re-sync (<1 second). The script invokes
`sync-web-site.sh` with the existing website checkout as the target
directory, skipping the `rm -rf` + `git clone` (~4 min) but running
all post-processing (asset moves, link rewrites, `index.html` creation,
and Qute escaping) through the same code path as a full sync.

To re-sync manually while the Roq dev server is still running (e.g.
after `just docs-preview` is done and you are iterating), run from
the `docs/` directory:

```bash
cd docs
./sync-web-site.sh main "$(pwd)/target/web-site"
```

Do not re-run `docs-preview.sh` while the server is still up — the
port check will reject it. Use the command above instead.

## Step 4 — Serve (from `docs/target/web-site`)

The site is built with [Quarkus Roq](https://docs.quarkiverse.io/quarkus-roq/dev/index.html),
a Quarkus-based static site generator. `./mvnw quarkus:dev` starts a
live-reload dev server — edits to content files are picked up
automatically without a server restart.

```bash
cd target/web-site
./mvnw quarkus:dev -DskipTests
```

The server starts on port 8042 by default (set in `config/application.properties`). To use a different port:

```bash
QUARKUS_HTTP_PORT=8081 ./mvnw quarkus:dev -DskipTests
```

Stop: `Ctrl-C` in the terminal running the dev server, or kill the background
process printed at the end of `just docs-preview`.

## Step 5 — Verify

The script auto-detects what you were working on and opens the right page:

| Content type | How detected | Preview URL |
|---|---|---|
| 1 guide | Recently modified `.adoc` in `docs/src/main/asciidoc/` | `/version/main/guides/<name>.html` (direct) |
| 2-4 guides | Multiple `.adoc` files modified | Opens a tab for each guide |
| 5+ guides | Many files modified | `/version/main/guides/` (listing) |
| Blog post | Recently modified `.adoc` in `content/posts/` | `/blog/<slug>/` (deep-link) |
| No changes | No recent `.adoc` changes found | `/` (homepage) |

## Iteration Loop

```
Edit .adoc → save → Step 2 (~1 min) → Step 3 re-sync (<1s) → browser auto-refreshes
```

Roq dev mode watches for file changes and triggers an incremental rebuild
automatically. Escalate to Step 1 when Step 2 fails or after significant
upstream changes.

## When to escalate to a root build

| Symptom | Action |
|---------|--------|
| Quick rebuild succeeds but content looks stale | Try `../mvnw -ntp clean package -Dasciidoctor.fail-if=ERROR` in `docs/` |
| `clean package` still broken or fails | Root build (Step 1) |
| Pulled new upstream changes to `main` | Root build (Step 1) |
| Root build is roughly a week old | Root build (Step 1) |
| New config properties or extensions added | Root build (Step 1) |

## Troubleshooting

**Port 8042 already in use** — Another process is using port 8042.
First, check whether it is a leftover preview from a previous run
(e.g. a `java` process launched by `mvnw`). If so, kill it and retry.
**Always tell the user before using a different port** — do not
silently switch ports without informing them. If the conflict cannot
be resolved, ask the user which port to use, then set the environment
variable:

```bash
QUARKUS_HTTP_PORT=8081 bash docs/docs-preview.sh
```

**Server process exited unexpectedly** — Maven started but then died.
Scroll up in the terminal to find the build error, or check the log
printed at the end of the run. Common causes: corrupted local Maven
repository, a missing or broken dependency, or a compile error.

**Changes not appearing** — Roq dev mode watches source files. If a
change is not picked up, stop and restart the dev server.

**Preview shows stale content after full sync** — Delete
`docs/target/web-site` and re-run `just docs-preview` to force a fresh
clone and sync.

**`./mvnw` not executable** — The Maven wrapper exists in the website
checkout but lacks the execute bit:

```bash
chmod +x docs/target/web-site/mvnw
```

Do not install Maven system-wide as a workaround. The repository-provided
wrapper pins the correct Maven version.

**`./mvnw` missing** — The website checkout inside `docs/target/web-site`
is incomplete or corrupted. Delete it and re-run to force a fresh clone:

```bash
rm -rf docs/target/web-site
just docs-preview
```

**Force a full root build** — Set `QUARKUS_DOCS_PREVIEW_FULL=1` before
running: `QUARKUS_DOCS_PREVIEW_FULL=1 just docs-preview`