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

Source locations

Quarkus doc sources are built and synced to the Quarkus.io website at release time.

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

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

The Asciidoc files can be found in the src/main/asciidoc directory within the docs module.

Templates

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

Concepts

Use src/main/asciidoc/_templates/template-concepts.adoc

How-To Guides

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

Reference

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

Tutorials

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

Output locations

Configuration references

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

Asciidoc output as HTML

A locally-rendered result of asciidoc processing (which is similar, but not identical, to that used to generate website documentation) is found in docs/target/generated-docs/

Titles

The title should use sentence case and the active tense. Search engines like good titles, too!

Concepts

Concept documents give context and provide explanations. A title for a concept doc might finish this thought, "Understanding …​ "

How-To Guides

The title should state exactly what the how-to guide shows. Consider starting with "How to…​ " and complete the sentence with a concise description of the task.

Reference

A reference guide title should concisely summarize the content of the document. It should not include the word 'reference'. Consider starting with "About …​"

Tutorials

The title of the tutorial should state what task the user will complete, with emphasis on the key topic or demonstrated activity. Creating an app, for example, is rarely the focus of a tutorial, though it is often a step along the path. An example title might complete this (long) sentence, "You will create an application that [uses x extension to] …​"

File naming conventions

Quarkus docs are stored in a fairly flat structure in an effort to make things easier to discover. The bulk of the file name should be some representation of its title. Use all lowercase letters, separate words with hyphens, and don’t use symbols or special characters.

Prefix

Use a common prefix to group related documents, e.g. all of the documents related to writing Quarkus docs are prefixed with doc-.

Suffix

The file name should reflect the type of document:

  • Concept documents should end in -concepts.adoc

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

  • References should end in -reference.adoc

  • Tutorials should end in -tutorial.adoc

Asciidoc syntax

Quarkus docs are built from source written using Asciidoc syntax.

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.

Automatic Table of Contents (TOC)

Use :toc: preamble in the document header to insert an automatically generated TOC after the abstract (or preamble) to the document. For example, this document has the following in its header:

[id="reference-doc-quarkus-documentation"]
= Quarkus documentation reference
include::attributes.adoc[]
:toc: preamble

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 as 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 re-organized to make it simpler to consume?

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

In general, prefer using url macros to using 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.

Cross-reference source attributes
:doc-examples: ./_examples
:imagesdir: ./images
:includes: ./includes

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-concepts.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]

1. Rhodes, B. Semantic Linefeeds. https://rhodesmill.org/brandon/2012/one-sentence-per-line/