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

Prerequisites

Quarkus docs are built from source written using Asciidoc, a lightweight markup language.

We suggest you have the following materials nearby:

Sources

  • Documentation for Quarkus core and most extensions is located in the docs directory of the Quarkus GitHub repository.

  • Docs for Quarkiverse or other third-party extensions are pulled directly from those repositories.

Building and previewing Quarkus documentation

Asciidoc syntax highlighting and the preview provided by an IDE can be sufficient for minor documentation changes. For significant changes or any changes related to Quarkus configuration documentation, we recommend that you run the build and view the 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 a few things:

  • Generated configuration properties documentation will be located in the target/asciidoc/generated/config/ directory.

  • Asciidoc output (html files) will be found in the docs/target/generated-docs/ directory.

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

$ ./mvnw -f docs clean install

If you change the configuration properties of an extension, rebuild that extension first (to regenerate the associated config docs in target/asciidoc/generated/config/), and then rebuild the docs module.

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.

Changes to docs for Quarkiverse or other third-party extensions should be submitted as pull requests in respective repository according to its contribution guide.

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 PRs has a single, focused purpose. For example:

  • A single PR that adds a configuration option for an extension and updates related materials (how-to, reference) to explain the change.

  • A single PR for related changes to several docs, e.g. updates to ensure a term is used consistently, correcting a recurring error, or moving repeated content into a shared file.

  • If there are extensive code changes as well as documentation changes, make a separate PR for the documentation changes and indicate the relationship in the issue description.

Once created, the PR will be tagged automatically as something containing documentation changes.