A detailed reference for the structure and composition of Quarkus documentation.
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
docsmodule 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.
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
- 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/
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:
| Content type | Should … | Good example | Bad example |
|---|---|---|---|
Concept |
|
Security and authentication mechanisms in Quarkus |
Discovering Reactive SQL Clients In Quarkus |
How-To Guide |
|
Secure your Quarkus application with WebAuthn authentication |
Applying WebAuthn Authentication In Quarkus |
Reference |
|
Hibernate Reactive API configuration properties |
Reference guide for Configuring Hibernate Reactive API Configuration Properties |
Tutorial |
|
Create a Quarkus application in JVM mode by using the quick start example |
Creating an App |
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
-
Quarkus docs use Asciidoc syntax. The following links provide background on Asciidoc syntax and general conventions.
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.
For optimum findability, add a short description using user-oriented keywords to summarize the document’s purpose, task, and intent in no more than three sentences. Good abstracts also mention the benefits of following this content and avoid filler words, such as: "This document..", "This tutorial..", and "The following.."
|
Important
|
The first sentence of the abstract must explain the value and some benefit of the content in less than 26 words because this automatically displays on the Quarkus guides homepage. |
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: preambleSection 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.
|
Tip
|
Deep nesting (
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.
|
Note
|
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. |
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.
link:attributes.adoc[role=include]When cross-referencing content, always use the inter-document xref: syntax and supply a human-readable label to your link.
xref:{doc-guides}/doc-concepts.adoc[Quarkus Documentation concepts] (1)-
The cross reference starts with
xref:, uses a cross-reference source attribute({doc-guides}), and provides a readable description:[Quarkus Documentation concepts]
The following variables externalize key information that can change over time, and so references to such information should be done by using the variable inside of {} curly brackets. The complete list of externalized variables for use is given in the following table:
| Property Name | Value | Description |
|---|---|---|
|
|
The current version of the project. |
|
|
The location of the project home page. |
|
|
The location of the getting started page. |
|
|
The location of the project GitHub organization. |
|
|
Quarkus GitHub URL common base prefix. |
|
|
Quarkus URL for git clone referenced by the documentation. |
|
|
Quarkus URL to main source archive. |
|
|
Quarkus URL to main blob source tree; used for referencing source files. |
|
|
Quarkus URL to main source tree root; used for referencing directories. |
|
|
Quarkus URL to the issues page. |
|
|
Quarkus URL to set of container images delivered for Quarkus. |
|
|
URL of our chat. |
|
|
Email used to subscribe to our mailing list. |
|
|
Mailing list index page. |
|
|
Quickstarts URL common base prefix. |
|
|
Quickstarts URL for git clone referenced by the documentation. |
|
|
Quickstarts URL to main source archive. |
|
|
Quickstarts URL to main blob source tree; used for referencing source files. |
|
|
Quickstarts URL to main source tree root; used for referencing directories. |
|
|
Recommended GraalVM version to use. |
|
|
The full flavor of GraalVM to use e.g. |