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:
-
An editor or IDE that provides syntax highlighting and previews for AsciiDoc, either natively or with a plugin.
-
The Quarkus documentation reference for required syntax and other conventions.
Sources
-
AsciiDoc files are in the
src/main/asciidoc
directory within thedocs
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 thetarget/asciidoc/generated/config/
directory. -
AsciiDoc output (
html
files) in thedocs/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:
|
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.