Quarkus style and content guidelines

提供指南帮助您提供清晰且一致的内容，这些内容也存在于 Quarkus 文档所需的 diataxis 结构和组成中。

Guidelines are provided to help you to contribute clear and consistent content that is also sourced in the required diataxis structure and composition of Quarkus documentation.

AsciiDoc syntax

Quarkus 文档使用 AsciiDoc 语法。以下链接提供了有关 AsciiDoc 语法和一般约定的背景信息。

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

较短的句子更容易阅读和翻译。尝试每个句子使用少于 32 个单词。

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

Website publication

该存储库中的内容会发布到 Quarkus.io website 中。

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

您的标题必须遵循适用于 Quarkus 内容类型的特定指导，如下表所述：

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 文档使用扁平层次结构。

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

Use a suffix that reflects the document type (optional):

  • -concept.adoc for concept documents

  • -howto.adoc for how-to guides

  • -reference.adoc for references

  • -tutorial.adoc for tutorials

Document structure

使用 Quarkus 模板以确保您的内容与首选的 Quarkus 文档结构和样式一致。

Use the Quarkus templates to ensure that your content is consistent with the preferred Quarkus documentation structure and style.

Document header

每个文档都应定义一个文档范围属性的标题，每个文档都应至少定义一个 ID 和一个标题，并包含常见的属性（_attributes.adoc）。

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 style and content guidelines (2)
:iokays-category: quarkus
:iokays-path: modules/ROOT/pages/_attributes.adoc
:keywords: Quarkus, 中文文档, 编程技术

:iokays-category: quarkus
:iokays-path: modules/ROOT/pages/_attributes-local.adoc
:iokays-category: quarkus
:iokays-path: modules/ROOT/pages/doc-reference.adoc (3)
:diataxis-type: {type} (4)
:categories: contributing (5)
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 diataxis type: concept, howto, reference, or tutorial.
5 Specify the relevant Categories (comma separated).

Other common document header 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. The value of this attribute is used in tiles or other descriptions on the website and is not required in newer diataxis-styled docs, as outlined in Abstracts (preamble). If not present, the first sentence of the abstract is automatically used to generate the tile summary.

处理文件范围属性时，请注意空格。文件头以第一个空行结束。

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

Abstracts (preamble)

正文中的第一段被视为摘要，也称为导言。添加一个简短的描述，以帮助您的受众快速找到并理解页面目的和意图。摘要的第一句提供了摘要，并会自动添加到 Quarkus guides homepage中的瓷砖上。

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:

  • 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…​"

    • "The following…​"

  • Brief: Is no more than three sentences long.

确保第一句话解释了内容的价值以及一些好处，且不超过 26 个词。

Ensure that the first sentence explains the value and some benefits of the content in 26 words or less.

如果第一句话太长或无法简化为适合网站瓷砖，您可以在文件头属性中定义 `:summary:`属性以达到此目的。有关更多信息，请参阅 Other common document header attributes。

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.

Semantic line breaks

段落、列表和表中的文本应分成更易于查看的部分Rhodes[role="bare"]https://rhodesmill.org/brandon/2012/one-sentence-per-line/]。在每个句子的末尾开始新的一行，并在子句之间的自然中断处拆分句子本身。

Text in paragraphs, lists, and tables should be broken into pieces that are easier to reviewB. Semantic Linefeeds. [role="bare"https://rhodesmill.org/brandon/2012/one-sentence-per-line/]. Start a new line at the end of each sentence, and split sentences themselves at natural breaks between clauses.

Sections

部分标题应采用句子大小写书写，而不是标题大小写。

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

从标题开始您的文档，在 AsciiDoc 中，标题定义为 = Level 0`标题。在适当的地方，将您的内容划分为子部分，在 AsciiDoc 中，子部分定义为 `== Level 1`到 `====== Level 5。请勿跳过任何级别。

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.

尽可能避免深度嵌套 (====== Level 4、====== Level 5)。如果您最终得到深度嵌套的部分，请考虑以下事项：

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?

关于内容类型和组织的更多信息，请参阅 Quarkus documentation content types。

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

Links

通常， url macros优于空白链接或自动链接。为链接提供人类可读文本，尤其是在链接包含在其他文本中间时。

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

URL 宏还支持 additional 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]

上述源生成 AsciiDoc Syntax Quick Reference.

The above source produces this AsciiDoc Syntax Quick Reference.

Cross-references

Quarkus 文档是从不同环境中的源构建的。

Quarkus documentation is built from source in a few different environments.

Cross-reference source attributes

在交叉引用中使用属性, 从而确保我们的文档可以在这些环境中构建。

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

{generated-dir}

Relative path to generated configuration *.adoc files

_images

Relative path to directory containing images

{includes}

Relative path to directory containing partial/reusable content

在交叉引用内容时, 始终使用交叉文档 `xref:`语法并为您链接提供人类可读的标签。

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-concept.adoc[Quarkus Documentation concepts] 1
1 The cross-reference starts with xref:, and provides a readable description: [Quarkus Documentation concepts].

Anchors for in-file and cross-file navigation

  • To create an anchored ID, use lower-case characters, separate each word with -, and enclose the ID in [[]] as in the example below.[source, asciidoc]

[[title-heading]]
== Title heading

  • To call an anchor created in the same file, insert the anchored ID in a <<>> xref macro.[source, asciidoc]

<<title-heading>>

  • To create an anchor with a custom URL caption example, specify the anchored ID and desired name separated by , without white space.[source, asciidoc]

<<title-heading,Title heading description that fits the context of your content>>

不要在逐字标题或章节说明中使用 <<>> 格式，例如 [Title heading]。

Do not use the <<>> format with the verbatim heading or section description, such as [Title heading].

  • To call an anchored ID from a different file, use the full file name and anchored ID separated by #, and specify the human-readable URL caption.[source, asciidoc]

xref:<other-file-name>.adoc#title-heading[Title heading]

  • To refer to another file, use the xref macro with the full file name syntax and always specify the human-readable URL caption.[source, asciidoc]

xref:<name-of-the-file>.adoc[Human-readable label]

关于锚定 ID 的更多详情, 请参阅 "为 Quarkus 文档提供支持" 指南的 Cross-reference in-file and cross-file content by using anchors部分。

For more details about anchored IDs, see the Cross-reference in-file and cross-file content by using anchors section of the "Contribute to Quarkus documentation" guide.

Cross-reference phrasing

为确保一致性和上下文清晰性, 根据以下指南构建您的交叉引用短语:

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

  • Provide a direct hyperlink to the section, using the xref guidance in the previous section.

  • Specify the full title of the section and use sentence case.

  • Add the definite article “the” before the section title and specify “section” directly after the title.

  • Add the definite article “the” and “Quarkus” before the title of the guide, unless the word “Quarkus" is already in the title.

  • Insert the title of the guide between double quotations and specify “guide” directly after the title.

  • If the context is needed, lead with the phrase:

    • "For more information about …​"

Table 3. Correct and incorrect cross-reference phrases
Correct Incorrect

For more information, see the Configuring the ValidatorFactory section of the Quarkus "Validation with Hibernate Validator" guide.

For more information, see the 'Configuring the ValidatorFactory' section of the VALIDATION WITH HIBERNATE VALIDATOR guide.

For more information, see the Generating a cache key with CacheKeyGenerator section of the Quarkus "Application Data Caching" guide.

For more information, see Generating a cache key with CacheKeyGenerator.

For more information, see the PKCE-related section of the Quarkus "OpenID Connect (OIDC) Authorization Code Flow Mechanism" guide.

For more information, see OpenID Connect (OIDC) Authorization Code Flow Mechanism.

Reference source code

将源代码和示例包含在文档中有很多方法。

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:

[source,java]

System.out.println("Hello, World!");









在教程等文档中，你可能希望引用定期构建和测试的源代码。Quarkus 文档构建会将 *-examples/yaml 文件中列出的源文件复制到 target/asciidoc/examples 目录中（从项目根目录开始）的扁平结构中。






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








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.









通过这种方式复制的内容由 {code-examples} 源属性引用。源文件中（如果存在）的文本字符串 {{source}} 将被替换为复制中源文件的路径。






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:[source, 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 文档被归为以下类别。






Quarkus documentation is grouped into the following categories.





Table 4. 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






native


Everything related to native executables






observability


Extensions and integrations for runtime and application observability






security


Security






serialization


Serialization






tooling


Tooling






web


Web






writing-extensions


Writing Extensions









通过向 document header 中的 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:








: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 5. Variables








Property Name
Value
Description







{quarkus-version}


{quarkus-version}


The current version of the project.






{quarkus-home-url}


{quarkus-home-url}


The location of the project home page.






{quarkus-org-url}


{quarkus-org-url}


The location of the project GitHub organization.






{quarkus-base-url}


{quarkus-base-url}


Quarkus GitHub URL common base prefix.






{quarkus-clone-url}


{quarkus-clone-url}


Quarkus URL for git clone referenced by the documentation.






{quarkus-archive-url}


{quarkus-archive-url}


Quarkus URL to main source archive.






{quarkus-blob-url}


{quarkus-blob-url}


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






{quarkus-tree-url}


{quarkus-tree-url}


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






{quarkus-issues-url}


{quarkus-issues-url}


Quarkus URL to the issues page.






{quarkus-images-url}


{quarkus-images-url}


Quarkus URL to set of container images delivered for Quarkus.






{quarkus-chat-url}


{quarkus-chat-url}


URL of our chat.






{quarkus-mailing-list-subscription-email}


{quarkus-mailing-list-subscription-email}


Email used to subscribe to our mailing list.






{quarkus-mailing-list-index}


{quarkus-mailing-list-index}


Mailing list index page.






{quickstarts-base-url}


{quickstarts-base-url}


Quickstarts URL common base prefix.






{quickstarts-clone-url}


{quickstarts-clone-url}


Quickstarts URL for git clone referenced by the documentation.






{quickstarts-archive-url}


{quickstarts-archive-url}


Quickstarts URL to main source archive.






{quickstarts-blob-url}


{quickstarts-blob-url}


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






{quickstarts-tree-url}


{quickstarts-tree-url}


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






{graalvm-version}


{graalvm-version}


Recommended GraalVM version to use.






{graalvm-flavor}


{graalvm-flavor}


The builder image tag of GraalVM to use e.g. jdk-17.