Quarkus style and content guidelines

Create new documentation files with the appropriate template for the content type:

Quarkus documentation uses a flat hierarchy.

The bulk of the file name should be some representation of its title. Use all lowercase letters, separate words with hyphens, and avoid symbols and special characters.

Each document should define a header for document-scoped attributes. Minimally, each document should define and id and a title, and include common attributes (_attributes.adoc).

The first paragraph in the main body is treated as the abstract, also referred to as the preamble. Add a short description that helps your audience quickly find and understand the purpose and intent of the page. The first sentence of the abstract provides a summary and gets automatically added to the tile on the Quarkus guides homepage.

Try to write the abstract by using the following guidelines:

If the first sentence is too long or cannot be simplified to fit on the website tile, you can define a :summary: attribute in the document header attributes to serve that purpose. For more information, see Other common document header attributes.

Text in paragraphs, lists, and tables should be broken into pieces that are easier to review^[1]. Start a new line at the end of each sentence, and split sentences themselves at natural breaks between clauses.

Section titles should be written in sentence case rather than title case.

Start your document with a title, which in AsciiDoc is defined as a = Level 0 heading. Where appropriate, divide your content into subsections, which in AsciiDoc are defined as == Level 1 to ====== Level 5. Do not skip any levels.

We use attributes in our cross-references to ensure our docs can be built across these environments.

When cross-referencing content, always use the inter-document xref: syntax and supply a human-readable label to your link.

For consistency and context clarity, use the following guidelines for constructing your cross-reference phrases:

There are many ways to include source code and examples in the documentation.

The simplest is to write it directly in the file, like this:

In documents like tutorials, you may want to reference source code that is built and tested regularly. The Quarkus documentation build copies source files enumerated in *-examples/yaml files into a flattened structure in the target/asciidoc/examples directory (from the project root).

Content copied in this way is referenced by the {code-examples} source attribute. The literal string {{source}} in the source file, if present, will be replaced with the path of the source file in the copy.

Quarkus documentation is grouped into the following categories.

Tag your content to improve findability by adding at least one category to the categories attribute line in the document header. To add multiple categories, use comma-separated values. For example:

The following variables externalize key information that can change over time. References to such information should use the variable inside of curly brackets, {}.

The complete list of externalized variables for use is given in the following table: