Quarkus 风格和内容指南
提供指南是为了帮助您贡献清晰且一致的内容，这些内容也来源于所需的 diataxis 结构和 Quarkus 文档的组成。
网站发布
此存储库中的内容会发布到 Quarkus.io 网站。
-
从 main 分支构建的文档每晚发布 (main-SNAPSHOT)。
-
其他分支的文档在发布时发布。
标题和标题
无论内容类型如何，请确保文档中的主标题和任何标题都符合以下条件
-
以目标为导向，并使用受众的语言和关键字
-
描述性强，避免填充词
-
每行 3-12 个单词和 50-80 个字符，以优化搜索引擎中的可查找性
-
采用句子大小写样式
您的标题和标题还必须遵循 Quarkus 内容类型的特定指南，如下表所述
| 内容类型 | 应该…… | 好的例子 | 不好的例子 |
|---|---|---|---|
概念 |
|
Quarkus 中的安全和身份验证机制 |
在 Quarkus 中发现响应式 SQL 客户端 |
操作指南 |
|
使用 WebAuthn 身份验证保护您的 Quarkus 应用程序 |
在 Quarkus 中应用 WebAuthn 身份验证 |
参考 |
|
Hibernate Reactive API 配置属性 |
配置 Hibernate Reactive API 配置属性的参考指南 |
教程 |
|
通过使用快速入门示例在 JVM 模式下创建一个 Quarkus 应用程序 |
创建一个应用程序 |
文件约定
源位置
-
AsciiDoc 文件位于 Quarkus GitHub 存储库的
docs模块中的src/main/asciidoc目录中。 -
配置文档是从 Java 源代码文件中的 JavaDoc 注释生成的。
-
Java、YAML 和其他源文件也可以被 AsciiDoc 文件引用。
输出位置
- 配置参考
-
配置参考文档是从 MicroProfile Config 源文件中发现的 Javadoc 注释生成的。 这些生成的文件位于
target/asciidoc/generated/config/中（从项目根目录开始）。 - AsciiDoc 输出到 HTML
-
AsciiDoc 处理在
docs/target/generated-docs/中创建 HTML 文件。
文档结构
使用 Quarkus 模板以确保您的内容与首选的 Quarkus 文档结构和样式保持一致。
文档标头
每个文档都应定义文档范围属性的标头。 至少，每个文档都应定义 ID 和标题，并包含通用属性 (_attributes.adoc)。
[id="doc-reference"] (1)
= Quarkus style and content guidelines (2)
\include::_attributes.adoc[] (3)
:diataxis-type: {type} (4)
:categories: contributing (5)| 1 | 使用文件名作为文档的 ID。 |
| 2 | 按照 标题和标题 中的指南定义文档标题。 |
| 3 | 包含通用文档属性。 |
| 4 | 指定 diataxis 类型：concept、howto、reference 或 tutorial。 |
| 5 | 指定相关的类别（逗号分隔）。 |
其他常用文档标头属性
:extension-status: 预览-
使用此属性来标记特殊类型的内容。有效值为：
experimental、preview、stable（通常不使用）和deprecated。 :summary: <text>-
使用摘要来提供文档的简明（26 个字或更少）描述。此属性的值用于网站上的磁贴或其他描述，并且在较新的 diataxis 样式的文档中不需要，如 摘要（前言）中所述。如果不存在，则摘要的第一句话会自动用于生成磁贴摘要。
| 在使用文档范围的属性时，请注意空格。文档标头以第一个空行结束。 |
摘要（前言）
正文中的第一段被视为摘要，也称为前言。 添加简短的描述，帮助您的读者快速找到并理解页面的目的和意图。 摘要的第一句话提供了一个摘要，并会自动添加到 Quarkus 指南主页上的磁贴中。
尝试使用以下准则编写摘要
-
以用户为导向：包含用户熟悉的术语和关键字。
-
简洁：避免自我指涉的表达方式和填充词，例如
-
“本文档……”
-
“本教程……”
-
“以下……”
-
-
简洁：不超过三句话。
|
确保第一句话以 26 个字或更少的字数解释内容的价值和一些好处。 |
如果第一句话太长或无法简化以适应网站磁贴，您可以在文档标头属性中定义 :summary: 属性来实现此目的。有关更多信息，请参阅其他常用文档标头属性。
语义换行
段落、列表和表格中的文本应分成更易于审核的片段[1]。 在每个句子的末尾开始一个新行，并在从句之间的自然中断处拆分句子本身。
章节
章节标题应以句子大小写而不是标题大小写书写。
以标题开始您的文档，在 AsciiDoc 中定义为 = Level 0 标题。 在适当的地方，将您的内容划分为小节，在 AsciiDoc 中定义为 == Level 1 到 ====== Level 5。 不要跳过任何级别。
|
应尽可能避免深度嵌套 (
有关内容类型和组织的更多信息，请参阅Quarkus 文档内容类型。 |
链接
通常，首选 URL 宏 而不是裸链接或自动链接。 为链接提供人类可读的文本，尤其是在将其包含在其他文本中间时。
|
带有属性的 URL 宏链接
URL 宏还支持 其他属性，这些属性可能相关，例如在新窗口中打开链接。 上面的源生成此AsciiDoc 语法快速参考。 |
交叉引用
Quarkus 文档是在几种不同的环境中从源代码构建的。
交叉引用源属性
我们在交叉引用中使用属性以确保我们的文档可以在这些环境中构建。
| 属性 | 描述 |
|---|---|
|
包含收集的示例源文件的目录的相对路径 |
|
文档指南的源示例的相对路径 |
|
生成的配置 |
|
包含图像的目录的相对路径 |
|
包含部分/可重用内容的目录的相对路径 |
交叉引用内容时，始终使用文档间 xref: 语法，并为您的链接提供人类可读的标签。
xref:doc-concept.adoc[Quarkus Documentation concepts] (1)| 1 | 交叉引用以 xref: 开头，并提供可读的描述：[Quarkus 文档概念]。 |
用于文件内和跨文件导航的锚点
-
要创建锚定 ID，请使用小写字符，用
-分隔每个单词，并将 ID 括在[[]]中，如下例所示。[[title-heading]] == Title heading -
要调用在同一文件中创建的锚点，请将锚定 ID 插入
<<>>xref 宏中。<<title-heading>> -
要创建带有自定义 URL 标题示例的锚点，请指定锚定 ID 和所需名称，用
,分隔，没有空格。<<title-heading,Title heading description that fits the context of your content>>不要将 <<>>格式与逐字标题或章节描述一起使用，例如<<标题标题>>。 -
要从不同的文件中调用锚定 ID，请使用完整的文件名和锚定 ID，用
#分隔，并指定人类可读的 URL 标题。xref:<other-file-name>.adoc#title-heading[Title heading] -
要引用另一个文件，请使用 xref 宏和完整的文件名语法，并始终指定人类可读的 URL 标题。
xref:<name-of-the-file>.adoc[Human-readable label]有关锚定 ID 的更多详细信息，请参阅“为 Quarkus 文档做出贡献”指南的 使用锚点交叉引用文件内和跨文件内容 章节。
交叉引用措辞
为了保持一致性和上下文清晰度，请使用以下指南来构建您的交叉引用短语
-
使用上一节中的
xref指导原则提供到章节的直接超链接。 -
指定章节的完整标题并使用句子大小写。
-
在章节标题之前添加定冠词“the”，并在标题之后直接指定“section”。
-
在指南标题之前添加定冠词“the”和“Quarkus”，除非标题中已包含“Quarkus”。
-
将指南的标题插入双引号之间，并在标题之后直接指定“guide”。
-
如果需要上下文，请以短语开头
-
“有关更多信息，请参阅……”
-
| 正确 | 不正确 |
|---|---|
有关更多信息，请参阅 Quarkus “使用 Hibernate Validator 进行验证”指南的 配置 ValidatorFactory 章节。 |
有关更多信息，请参阅 使用 HIBERNATE VALIDATOR 指南进行验证 的“配置 ValidatorFactory”章节。 |
有关更多信息，请参阅 Quarkus “应用程序数据缓存”指南的 使用 CacheKeyGenerator 生成缓存键 章节。 |
有关更多信息，请参阅 使用 CacheKeyGenerator 生成缓存键。 |
有关更多信息，请参阅 Quarkus “OpenID Connect (OIDC) 授权码流程机制”指南的 与 PKCE 相关的章节。 |
有关更多信息，请参阅 OpenID Connect (OIDC) 授权码流程机制。 |
引用源代码
有许多方法可以在文档中包含源代码和示例。
最简单的方法是直接将其写入文件中，如下所示
[source,java]
----
System.out.println("Hello, World!");
----在教程之类的文档中，您可能需要引用定期构建和测试的源代码。 Quarkus 文档构建将 *-examples/yaml 文件中枚举的源文件复制到 target/asciidoc/examples 目录中的扁平结构中（从项目根目录开始）。
examples:
- source: path/to/source/file/SomeClassFile.java (1)
target: prefix-simplified-unique-filename.java (2)| 1 | 定义要复制的源的路径 |
| 2 | 定义在将文件复制到 target/asciidoc/examples 目录时要使用的简化目标文件名。 |
以这种方式复制的内容由 {code-examples} 源属性引用。 如果存在，源文件中的文字字符串 {{source}} 将被替换为副本中源文件的路径。
-
要复制的源文件是
integration-tests/micrometer-prometheus/src/main/java/documentation/example/telemetry/micrometer/tutorial/ExampleResource.java -
我们要在文档中使用的目标文件名是
telemetry-micrometer-tutorial-example-resource.java. -
源文件名和目标文件名在
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 -
然后使用以下路径引用此源文件中的片段
{code-examples}/telemetry-micrometer-tutorial-example-resource.java. -
源文件包含以下注释
// Source: {{source}}
-
复制的文件改为包含此注释
// Source: integration-tests/micrometer-prometheus/src/main/java/io/quarkus/doc/micrometer/ExampleResource.java
文档属性和变量
类别
Quarkus 文档分为以下类别。
| 类别 | 描述 |
|---|---|
|
支持其他语言，即 Kotlin 和 Scala |
|
Quarkus 运行时和生态系统架构 |
|
业务自动化集成 |
|
对云服务的集成和支持 |
|
命令行应用程序 |
|
与其他语言和框架的兼容性 |
|
指导和参考，以帮助您为 Quarkus 做出贡献。 |
|
有关 Quarkus 如何工作的信息 |
|
与在 Quarkus 中使用数据源相关的主题 |
|
入门材料 |
|
支持集成扩展 (Camel) |
|
与消息传递系统（如 Kafka、AMQP 或 RabbitMQ）的集成。 |
|
其他 |
|
与本机可执行文件相关的所有内容 |
|
运行时和应用程序可观察性的扩展和集成 |
|
安全 |
|
序列化 |
|
工具 |
|
Web |
|
编写扩展 |
通过在文档标头中的类别属性行中添加至少一个类别来标记您的内容以提高可查找性。 要添加多个类别，请使用逗号分隔的值。 例如
:categories: contributing, dataQuarkus 文档变量
以下变量外部化了可能随时间变化的关键信息。 对此类信息的引用应使用大括号 {} 内的变量。
下表给出了要使用的外部化变量的完整列表
| 属性名称 | 值 | 描述 |
|---|---|---|
|
|
项目的当前版本。 |
|
项目主页的位置。 |
|
|
项目 GitHub 组织的位置。 |
|
|
Quarkus GitHub URL 常见基本前缀。 |
|
|
文档引用的 Quarkus |
|
|
Quarkus 到 main 源代码存档的 URL。 |
|
|
Quarkus 到 main blob 源代码树的 URL； 用于引用源文件。 |
|
|
Quarkus 到 main 源代码树根的 URL； 用于引用目录。 |
|
|
Quarkus 到问题页面的 URL。 |
|
|
Quarkus URL 到为 Quarkus 交付的容器映像集。 |
|
|
我们的聊天室的 URL。 |
|
|
用于订阅我们的邮件列表的电子邮件。 |
|
|
邮件列表索引页。 |
|
|
Quickstarts URL 常见基本前缀。 |
|
|
文档引用的 Quickstarts |
|
|
|
Quickstarts 到 main 源代码存档的 URL。 |
|
Quickstarts 到 main blob 源代码树的 URL； 用于引用源文件。 |
|
|
Quickstarts 到 main 源代码树根的 URL； 用于引用目录。 |
|
|
|
建议使用的 GraalVM 版本。 |
|
|
要使用的 GraalVM 的构建器图像标记，例如 |
