Back to Guides

How to contribute documentation

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:

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:

  1. Revise the Javadoc in the extension

  2. Build the extension to regenerate content in target/asciidoc/generated/config/

  3. 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.