Back to Guides

How to contribute documentation

Prerequisites
Sources
Preview and build Quarkus documentation
Lint documentation changes with Vale
Creating pull requests for doc updates

Outline the recommended steps for making successful contributions to Quarkus documentation.

Prerequisites

Quarkus docs use AsciiDoc, a lightweight markup language.

We suggest you have the following materials nearby:

An editor or IDE that provides syntax highlighting and previews for AsciiDoc, either natively or with a plugin.
The AsciiDoc syntax reference
The Quarkus documentation reference for required syntax and other conventions.

Sources

AsciiDoc files are in the src/main/asciidoc directory within the docs module of the Quarkus GitHub repository.
Configuration documentation is generated from JavaDoc comments in Java source files.
Java, YAML, and other source files can also be referenced by AsciiDoc files.

Preview and build Quarkus documentation

AsciiDoc syntax highlighting and the preview provided by an IDE may be enough for minor documentation changes. For significant changes or updates to generated configuration documentation, you should build the docs module and view resulting output before submitting your changes for review.

The following will build all modules in the Quarkus repository (except test modules) and install them in your local maven repository with the 999-SNAPSHOT version:

./mvnw -DquicklyDocs

This will produce:

Generated AsciiDoc (adoc files) describing configuration properties in the target/asciidoc/generated/config/ directory.
AsciiDoc output (html files) in the docs/target/generated-docs/ directory.
YAML files containing metadata for all documents individually (docs/target/indexByFile.yaml) and grouped by document type (target/indexByType.yaml).
YAML files that list metadata errors by file (docs/target/errorsByFile.yaml) and by error type (docs/target/errorsByType.yaml)

As you make changes, you can rebuild the docs module specifically to update the generated HTML:

./mvnw -f docs clean install

When updating extension configuration:

Revise the Javadoc in the extension
Build the extension to regenerate content in target/asciidoc/generated/config/
Build the docs module to view the rendered results.

Lint documentation changes with Vale

Our builds use Vale to check grammar, style, and word usage in the English versions of our documents. The configuration for vale is in the docs/.vale directory.

The Vale configuration file is docs/.vale/vale.ini.

Containerized Vale

This approach requires a working container runtime (Docker or Podman).

The docs module has a JUnit 5 test that will run the Vale linter in a container (using Testcontainers). It verifies both Quarkus document metadata and Vale style rules.

Run the test in one of the following ways:

./mvnw -f docs test -Dvale -DvaleLevel=suggestion (1)
./mvnw -f docs test -Dvale=git -DvaleLevel=warning (2)
./mvnw -f docs test -Dvale='doc-.*' -DvaleLevel=error (3)

1	Run the Vale linter for all `*.adoc` files in the `src/main/asciidoc` directory of the `docs` module. Include suggestions, warnings, and errors in the results.
2	Run the Vale linter for any modified `*.adoc` files in the `docs` module (`git status`). Include warnings and errors in the results.
3	Run the Vale linter for `*.adoc` files that match the regular expression (Java Pattern syntax). Include errors in the results.

Use the Vale CLI

If you install the install the Vale CLI, you must specify the configuration file along with the directory or list of files to scan:

vale --config=docs/.vale/vale.ini --minAlertLevel=warning docs/src/main/asciidoc

See the Vale CLI Manual for details.

Vale IDE plugins

Vale IDE integrations rely on installation the Vale CLI.

Each has it’s own configuration requirements. The Visual Studio Code IDE extension, for example, requires two workspace settings:

"vale.valeCLI.config": "/path/to/quarkus/docs/.vale/vale.ini",
"vale.valeCLI.path": "/path/to/vale"

Creating pull requests for doc updates

Submit your proposed changes to the core Quarkus docs by creating a pull request against the main branch of the Quarkus repository from your own repository fork.

Reviews for code and documentation have different (but overlapping) participants. To simplify collaborative review, either isolate changes to docs in their own PRs, or ensure that the PR has a single, focused purpose For example:

Create a single PR that adds a configuration option for an extension and updates related materials (how-to, reference) to explain the change.
Create a single PR for related changes to a group of documents, some examples: correcting the usage of a term, correcting a recurring error, or moving common content into a shared file.
If there are extensive code changes and documentation changes, create a separate PR for the documentation changes and include the relationship in the issue description.

Pull requests that contain changes to documentation will have the area/documentation label added automatically.