Back to Guides

About Quarkus documentation

A detailed reference for the structure and composition of Quarkus documentation.

AsciiDoc syntax

Quarkus docs use AsciiDoc syntax. The following links provide background on AsciiDoc syntax and general conventions.

Language and grammar

Write clear, concise, and consistent technical information in US English. Write for a global audience with localization, translation, inclusivity, and diversity in mind. Try to use the following grammar styles:

Sentence length

Shorter sentences are much easier to read and translate. Try to use less than 32 words per sentence.

Website publication

Content from this repository is published to the Quarkus.io website.

  • Documentation built from the main branch is published nightly (main-SNAPSHOT).

  • Documentation for other branches is published at release time.

Titles and headings

Regardless of content type, ensure that the main title and any headings in your document are:

  • Goal-oriented and use the language and keywords of the audience

  • Descriptive and avoid filler words

  • Between 3-12 words and 50-80 characters per line to optimize findability in search engines

  • In sentence case capitalization style

Your titles and headings must also follow the specific guidance for the Quarkus content types, as outlined in the following table:

Table 1. Title guidance for different Quarkus content types
Content type Should …​ Good example Bad example

Concept

  • Start with a noun that names the concept or topic

  • Never start with an active verb, for example, an action word like configure, install, or start

  • Finish the implied sentence: "Understanding …​"

Security and authentication mechanisms in Quarkus

Discovering Reactive SQL Clients In Quarkus

How-To Guide

  • Start with an active verb in the imperative verb form, for example, "Create a …​" or "Secure a …​"

  • Be action-oriented or task-oriented, rather than feature-oriented

  • Finish the implied sentence: "How to …​"

Secure your Quarkus application with WebAuthn authentication

Applying WebAuthn Authentication In Quarkus

Reference

  • Use a noun phrase to concisely summarize the content of the document

  • Not include the word 'reference'

  • Finish the implied sentence: "About …​"

Hibernate Reactive API configuration properties

Reference guide for Configuring Hibernate Reactive API Configuration Properties

Tutorial

  • Start with an active verb in the imperative verb form, for example, "Create a …​" or "Secure a …​"

  • State what task the user will complete, with emphasis on the key topic or demonstrated activity

  • Be action-oriented or task-oriented, rather than feature-oriented

  • Be led by the needs of the user in learning mode.

  • Finish the implied sentence: "In this tutorial, you will …​"

Create a Quarkus application in JVM mode by using the quick start example

Creating an App

File conventions

Source locations

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

Output locations

Configuration references

Configuration reference documentation is generated from Javadoc comments discovered in MicroProfile Config source files. These generated files are in target/asciidoc/generated/config/ (from the project root).

AsciiDoc output to HTML

AsciiDoc processing creates HTML files in docs/target/generated-docs/.

Templates

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

Concepts

Use docs/src/main/asciidoc/_templates/template-concept.adoc

How-To Guides

Use docs/src/main/asciidoc/_templates/template-howto.adoc

Reference

Use docs/src/main/asciidoc/_templates/template-reference.adoc

Tutorials

Use docs/src/main/asciidoc/_templates/template-tutorial.adoc

File names

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.

Prefix

Use a common prefix to group related documents. Documents related to writing and contributing to Quarkus docs share the doc- prefix, for example.

Suffix

The file name should reflect the document type:

  • Concept documents should end in -concept.adoc

  • How-to guides should end in -howto.adoc

  • References should end in -reference.adoc

  • Tutorials should end in -tutorial.adoc

Document structure

Document header

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

[id="doc-reference"] (1)
= Quarkus documentation reference (2)
\include::_attributes.adoc[] (3)
:categories: contributing (4)
1 Use the filename as the ID for the document.
2 Define the document title following guidance in Titles and headings
3 Include common document attributes
4 Specify the relevant Categories (comma separated)

Other common document attributes:

:extension-status: preview

Use this attribute to flag special types of content. Valid values: experimental, preview, stable (not usually used), and deprecated.

:summary: <text>

Use the summary to provide a concise (26 words or less) description of the document. This attribute will be used in tiles or other descriptions on the website. If not present, the contents of the preamble will be used instead.

Take care with whitespace when working with document-scoped attributes. The document header ends with the first blank line.

Abstracts (preamble)

Add a short description that helps your audience to quickly find and understand the purpose and intent of the page.

Try to write the abstract by using the following guidelines:

  • User oriented: Contains terms and keywords that are familiar to users.

  • Concise: Avoids self-referential expressions and filler words, for example, "This document..", "This tutorial..", or "The following.."

  • Brief: Is no more than three sentences long.

The first sentence of the abstract must explain the value and some benefit of the content in less than 27 words because this automatically displays on the Quarkus guides homepage.

Semantic line breaks

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.

Using sections

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

All documents should start with a Title (a = Level 0 heading), and should be broken into subsections where appropriate (== Level 1 to ====== Level 5) without skipping any levels.

Deep nesting (====== Level 4, ====== Level 5) should be avoided whenever possible. If you end up with deeply nested sections, think about the following:

  • Is this information in the right place? For example, if this is a reference, should some of this content be moved to a concept doc or how-to guide instead?

  • Can the content be reorganized to make it simpler to consume?

See Quarkus documentation concepts for more information about content types and organization.

In general, prefer url macros to bare or automatic links. Provide human-readable text for the link, especially if it is included in the middle of other text.

A URL Macro link with attributes

The URL macro also supports additional attributes that may be relevant, like opening a link in a different window.

https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[AsciiDoc Syntax Quick Reference,window=_blank,opts=nofollow]

The above source produces this link: AsciiDoc Syntax Quick Reference.

Cross-references

Quarkus documentation is built from source in a few different environments. We use attributes in our cross-references to ensure our docs can be built across these environments.

Table 2. Cross-reference source attributes
Attribute Description

{code-examples}

Relative path to directory containing collected example source files

{doc-examples}

Relative path to source examples for documentation guides

{doc-guides}

Relative path to documentation adoc files

{generated-dir}

Relative path to generated configuration *.adoc files

{imagesdir}

Relative path to directory containing images

{includes}

Relative path to directory containing partial/reusable content

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

Cross-reference example
xref:{doc-guides}/doc-concept.adoc[Quarkus Documentation concepts] (1)
1 The cross reference starts with xref:, uses a cross-reference source attribute({doc-guides}), and provides a readable description: [Quarkus Documentation concepts].

Reference source code

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

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

[source,java]
----
System.out.println("Hello, World!");
----

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

examples:
- source: path/to/source/file/SomeClassFile.java (1)
  target: prefix-simplified-unique-filename.java (2)
1 define the path of source to be copied
2 define the simplified target file name to use when copying the file into the target/asciidoc/examples directory.

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.

Micrometer example
  • The source file to be copied is:

    integration-tests/micrometer-prometheus/src/main/java/documentation/example/telemetry/micrometer/tutorial/ExampleResource.java

  • The target file name we want to use in docs is:

    telemetry-micrometer-tutorial-example-resource.java.

  • The source and target file names are declared in docs/src/main/asciidoc/telemetry-examples.yaml:

    examples:
    - source: integration-tests/micrometer-prometheus/src/main/java/io/quarkus/doc/micrometer/ExampleResource.java
      target: telemetry-micrometer-tutorial-example-resource.java
  • Snippets from this source file are then referenced with the following path:

    {code-examples}/telemetry-micrometer-tutorial-example-resource.java.

  • The source file contains the following comment:

// Source: {{source}}
  • The copied file contains this comment instead:

// Source: integration-tests/micrometer-prometheus/src/main/java/io/quarkus/doc/micrometer/ExampleResource.java

Document attributes and variables

Categories

Quarkus documentation is grouped into the following categories.

Table 3. Categories
Category Description

alt-languages

Support for other languages, namely Kotlin and Scala

architecture

Quarkus runtime and ecosystem architecture

business-automation

Business automation integrations

cloud

Integrations and support for cloud services

command-line

Command Line Applications

compatibility

Compatibility with other languages and frameworks

contributing

Guidance and references to help you contribute to Quarkus.

core

Information about how the Quarkus works

data

Topics related to using data sources with Quarkus

getting-started

Getting started materials

integration

Support for integration extensions (Camel)

messaging

Integrations with messaging systems like Kafka, AMQP, or RabbitMQ.

miscellaneous

Miscellaneous

observability

Extensions and integrations for runtime and application observability

reactive

Extensions that support reactive technologies and techniques

security

Security

serialization

Serialization

tooling

Tooling

web

Web

writing-extensions

Writing Extensions

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:

:categories: contributing, data

Quarkus documentation variables

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:

Table 4. Variables
Property Name Value Description

{quarkus-version}

2.16.0.Final

The current version of the project.

{quarkus-home-url}

https://quarkus.io

The location of the project home page.

{quarkus-org-url}

https://github.com/quarkusio

The location of the project GitHub organization.

{quarkus-base-url}

https://github.com/quarkusio/quarkus

Quarkus GitHub URL common base prefix.

{quarkus-clone-url}

https://github.com/quarkusio/quarkus.git

Quarkus URL for git clone referenced by the documentation.

{quarkus-archive-url}

https://github.com/quarkusio/quarkus/archive/main.zip

Quarkus URL to main source archive.

{quarkus-blob-url}

https://github.com/quarkusio/quarkus/blob/main

Quarkus URL to main blob source tree; used for referencing source files.

{quarkus-tree-url}

https://github.com/quarkusio/quarkus/tree/main

Quarkus URL to main source tree root; used for referencing directories.

{quarkus-issues-url}

https://github.com/quarkusio/quarkus/issues

Quarkus URL to the issues page.

{quarkus-images-url}

https://github.com/quarkusio/quarkus-images/tree

Quarkus URL to set of container images delivered for Quarkus.

{quarkus-chat-url}

https://quarkusio.zulipchat.com

URL of our chat.

{quarkus-mailing-list-subscription-email}

quarkus-dev+subscribe@googlegroups.com

Email used to subscribe to our mailing list.

{quarkus-mailing-list-index}

https://groups.google.com/d/forum/quarkus-dev

Mailing list index page.

{quickstarts-base-url}

https://github.com/quarkusio/quarkus-quickstarts

Quickstarts URL common base prefix.

{quickstarts-clone-url}

https://github.com/quarkusio/quarkus-quickstarts.git

Quickstarts URL for git clone referenced by the documentation.

{quickstarts-archive-url}

https://github.com/quarkusio/quarkus-quickstarts/archive/main.zip

Quickstarts URL to main source archive.

{quickstarts-blob-url}

https://github.com/quarkusio/quarkus-quickstarts/blob/main

Quickstarts URL to main blob source tree; used for referencing source files.

{quickstarts-tree-url}

https://github.com/quarkusio/quarkus-quickstarts/tree/main

Quickstarts URL to main source tree root; used for referencing directories.

{graalvm-version}

22.3

Recommended GraalVM version to use.

{graalvm-flavor}

22.3-java17

The builder image tag of GraalVM to use e.g. 22.3-java17. Use a java17 version.