Contribute to Quarkus documentation

通过使用推荐的 diataxis 内容类型、步骤、工作流和样式指南来确保内容在 Quarkus 网站门户上成功呈现，从而为文档做出贡献。 Quarkus 文档使用 AsciiDoc 标记。

Table of Contents

Prerequisites
Locate the source files for Quarkus docs
Create Quarkus content in AsciiDoc

Prerequisites

您有编辑器或 IDE，它本机或通过插件提供 AsciiDoc 的语法高亮和预览。
您已查看以下 Quarkus 贡献者资源：
- Quarkus“贡献指南”中的 Documentation 部分。
- 用于了解所需语法、首选样式和其他约定的 Quarkus style and content guidelines。
- Quarkus documentation content types。
您附近有 AsciiDoc syntax reference。

Locate the source files for Quarkus docs

AsciiDoc 文件位于 docs 的 Quarkus GitHub repository 模块中的 src/main/asciidoc 目录中。
Quarkus 文档模板位于 docs 的 Quarkus GitHub repository 模块中的 src/main/asciidoc/_templates 目录中。
配置文档由 Java 源文件中的 JavaDoc 注释生成。
Java、YAML 和其他源文件也可以通过 AsciiDoc 文件 referenced。
Quarkus documentation menu 页面，也称为文档索引页面，取自 quarkusio.github.io 仓库。

Create Quarkus content in AsciiDoc

为确保您的内容在 Quarkus documentation home page 上正确显示，请使用以下步骤：

在你提供的 Diataxis 内容类型中，找到最适合你要添加的内容类型的。

为了帮助你做出决定，请参阅在“关于 Quarkus 文档”页面的 Titles and headings 中的内容类型说明。

进入 src/main/asciidoc/_templates 目录，并为所选内容类型复制相关的模板。请务必：
- 使用 <category>-<titlekeyword>-<titlekeyword>.adoc 的文件名语法。例如，security-basic-authentication.adoc。
- 如果合理的话，在文件名中包括二轴类型（概念、操作方法、参考、教程）。例如，telemetry-micrometer.adoc 是一个参考，telemetry-micrometer-tutorial.adoc 是一个教程。
- 将该文件保存到 quarkus 存储库的 docs/src/main/asciidoc 目录中。
设置最低所需标题信息，以确保内容在网站门户和文档主页中正确呈示，如下例所示：[source, asciidoc]

[id="security-basic-authentication"] 1
= Secure a Quarkus application with basic authentication 2
link:_attributes.adoc[role=include]
:iokays-category: quarkus
:iokays-path: modules/ROOT/pages/doc-contribute-docs-howto.adoc 3
:diataxis-type: howto 4
:categories: security,web 5
6

1	将 `id` 值设置为与文件名相同，但不包含扩展名。
2	有关如何为每个内容类型创建好标题的信息，请参见“Quarkus 样式和内容指南”页面上的 Titles and headings。
3	`_attributes.adoc` include 对于确保解析属性并生成目录是必需的。
4	指定二轴类型： `concept`、`howto`、`reference` 或 `tutorial`。
5	设置至少一个类型以确保在 Quarkus documentation home page 上找到内容。有关 Quarkus 类别的列表，请参阅“Quarkus 样式和内容指南”页面上的 Document attributes and variables。
6	在所有文档属性之后和摘要之前插入一个空行。

确保 document id 和标题、属性 include (include::_attributes.adoc[] :iokays-category: quarkus :iokays-path: modules/ROOT/pages/doc-contribute-docs-howto.adoc) 和其他文档属性声明 (:attribute:) 之间没有空行。

添加一个抽象部分，描述该指南的目的。====== 抽象部分的第一句话必须在不超过 27 个单词内解释内容的价值和一些好处，因为这会自动显示在 Quarkus guides homepage。在摘要之前和之后还必须有一个换行符。

有关最低标题要求的更多信息，请参阅“Quarkus 样式和内容指南”页面上的 Document structure。

== Add a prerequisites section

对于操作方法和教程主题，请在摘要之后包含一个先决条件部分。声明先决条件可以阐明操作方法和教程内容的起点。即使对知识渊博的用户来说它们看起来很明显，也应将它们包含在内。

An example prerequisite with callout explanations

.Prerequisites 1

:prerequisites-time: 30 minutes 2
include::{includes}/prerequisites.adoc[] 3
* <an additional prerequisite> 4

1	先决条件的章节标题
2	可选：修改先决条件的属性
3	包含有关 `prerequisites.adoc` 文件的声明
4	可选：属性中未包含的附加先决条件

The default prerequisites

默认情况下，include::./_includes/prerequisites.adoc[] 会插入以下 Asciidoc：

link:{includes}/prerequisites.adoc[role=include]

Using attributes to modify the prerequisites

您可以通过在 include::./_includes/prerequisites.adoc[] 宏前添加以下属性来选择添加、删除或修改默认先决条件。

{prerequisites-time}: <number of minutes> 覆盖默认的 15 分钟值。例如，{prerequisites-time}: 30 添加 * Roughly 30 minutes。
{prerequisites-no-maven} 删除 * Apache Maven <maven version>。
{prerequisites-docker} 添加 * A working container runtime (Docker or Podman)。
{prerequisites-docker-compose} 添加 Docker and Docker Compose or Podman, and Docker Compose。
{prerequisites-no-cli} 删除 * Optionally the Quarkus CLI if you want to use it。
{prerequisites-no-graalvm} 或 {prerequisites-graalvm-mandatory} 删除 * Optionally Mandrel or GraalVM installed and configured appropriately if you want to build a native executable (or Docker if you use a native container build)。
{prerequisites-graalvm-mandatory} 添加 * Mandrel or GraalVM installed and configured appropriately。

有关这些属性的更多信息，请检查 docs/src/main/asciidoc/_includes/prerequisites.adoc 文件的内容。

== Retire and redirect an existing Quarkus AsciiDoc source file

随着内容的发展，您可能希望将现有 Quarkus 内容重组到一个或多个内容类型中，并弃用现有的 AsciiDoc 源文件。

如果您要弃用或重命名已发布的 Quarkus AsciiDoc 源文件，请确保重组不会中断到原始内容的现有书签和链接。通过使用以下步骤在 Quarkus.io Website GitHub 存储库中配置 URL 重定向：

切换到 quarkusio/quarkusio.github.io 存储库并打开 _redirects/guides 文件夹。
使用与您要弃用的原始 AsciiDoc 源文件名相匹配的文件名创建 Markdown 格式的重定向文件。
向 Markdown 重定向文件添加以下内容：[source, markdown]

---
permalink: /guides/<original_asciidoc_filename>/index.html (1)
newUrl: /guides/<new_asciidoc_filename> (2)
---

其中：

1	原始 AsciiDoc 源文件的名称，不带 `.adoc` 文件扩展名。
2	要重定向到的 AsciiDoc 源文件的名称，不带 `.adoc` 文件扩展名。

Table 1. Example
原始 AsciiDoc 源文件的名称	要重定向到的目标文件的名称	Redirection file	Example pull request
`security-getting-started`	`security-overview-concept`	`security-getting-started.md`	PR #1579

== Use anchors to cross-reference in-file and cross-file content

锚点（也称作 ID）可在文档中的几乎任何地方定义，包括章节标题、独立标题、段落、图片、分隔块、内联句子等。

这些锚点的调用功能会根据你是调用本地 ID 还是另一个文件中的 ID 而有所不同，但固定锚点 ID 的创建方法保持不变。

=== Create an anchored ID

为要引用的新文件或章节创建 ID，按以下方式插入锚点 ID：

Use lower-case characters.
用破折号将每个单词分开。
用双方括号将 ID 括起来。

Anchored ID creation example

在本部分中，我们将使用在 2 级标题上方创建的锚点以作演示。

[[title-heading]]
== Title heading

=== Call an anchored ID in the same file

要在同一文件中调用创建的锚点，请插入 <<>> xref 宏中的固定锚点 ID。

Inter-document anchored ID call example

<<title-heading>>

此宏会创建一个 URL，其名称会自动从固定的标题、章节或表格中获取。

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

要为 URL 指定非默认的标题，请指定锚定 ID 和通过 , 分开的所需名称（不含空格）。

Anchor with a custom URL caption example

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

=== Call an anchored ID from a different file

要在另一个文件中调用创建的锚点，请将锚点插入到 xref 宏，并指定托管文件的完整名称和所需的锚定 ID。

Cross-document anchored ID call example

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

拆分此示例，我们会使用 xref 宏来引用另一个文件 (xref:<name-of-the-file>.adoc[Human-readable label])，并在文件名称后立即插入目标节的锚点 ID (#title-heading)。

有关编写交叉引用的更多指南，包括推荐的路径属性，请参见 Cross-references。

== Preview and build Quarkus documentation

在提交拉取请求之前，请使用以下构建方法之一预览 AsciiDoc 源的 HTML 输出：

对于轻微的文档更改，你可以使用 IDE 提供的 AsciiDoc 语法高亮显示和预览。
如果需要对生成的配置文档进行重大更改或更新，请按照以下部分所述，在本地构建 docs 模块并运行 Vale linter。

=== Build the docs module locally

以下将构建 Quarkus 存储库（文档和测试模块除外）中的所有模块，并将它们与 999-SNAPSHOT 版本安装到本地 maven 存储库中：

./mvnw -Dquickly

以下将构建 Quarkus 存储库（测试模块除外）中的所有模块，并将它们与 `999-SNAPSHOT`版本安装到本地 maven 存储库中：

./mvnw -DquicklyDocs

运行 -DquicklyDocs 会生成以下内容：

描述 target/asciidoc/generated/config/ 目录中配置属性的 AsciiDoc（adoc 文件）。
docs/target/generated-docs/ 目录中的 AsciiDoc 输出（html 文件）。
包含有关所有文档的元数据的 YAML 文件（单独的 docs/target/indexByFile.yaml 和按文档类型分组的 target/indexByType.yaml）。
按文件 (docs/target/errorsByFile.yaml) 和按错误类型 (docs/target/errorsByType.yaml) 列出元数据错误的 YAML 文件。

查看生成的结果并修复所有问题，然后在提交 PR 以供审阅之前提交更改。

在进行更改时，你可以重建 docs 模块，专门更新生成的 HTML：

./mvnw -f docs clean install

更新扩展配置时：

修改扩展中的 Javadoc。
构建扩展以在 target/asciidoc/generated/config/ 中重新生成内容。
构建 docs 模块以查看呈现的结果。

== Lint documentation changes with Vale

我们的构建使用 Vale 检查文档英文版中的语法、格式和单词用法。我们创建了自己的 Vale 规则集，以确保内容符合首选的 Quarkus 格式指南。

Vale 的 Quarkus 配置位于 docs/.vale.ini。
Quarkus 格式规则以 YAML 格式位于 docs/.vale/styles 目录中。

=== Containerized Vale

此方法需要可工作的容器运行时环境 (Docker 或 Podman)。

@1 模块有一个 JUnit 5 测试，它将在容器中运行 Vale linter（使用 @2）。它验证 Quarkus 文档元数据和 Vale 样式规则。

使用以下任一方式来运行测试：

./mvnw -f docs test -Dvale -DvaleLevel=suggestion (1)
./mvnw -f docs test -Dvale=git -DvaleLevel=warning (2)
./mvnw -f docs test -Dvale='doc-.*' -DvaleLevel=error (3)

1	在 @5 模块的 @4 目录中运行所有 @3 文件的 Vale linter。在结果中包含建议、警告和错误。
2	在 @7 模块 (@8) 中运行所有已修改 @6 文件的 Vale linter。在结果中包含警告和错误。
3	在符合正则表达式（Java Pattern 语法）的 @9 文件中运行 Vale linter。在结果中包含错误。

=== Use the Vale CLI

如果你安装了 @10，则必须指定配置文件和要扫描的目录或文件列表：

# Run from the Quarkus project root
vale --config=docs/.vale.ini --minAlertLevel=warning docs/src/main/asciidoc

# Run from within the docs directory
vale --minAlertLevel=warning src/main/asciidoc

更多信息，请参阅 @11。

=== Vale IDE plugins

@12 要求安装 Vale CLI。

每个 IDE 集成有其自己的配置要求。例如，Visual Studio Code IDE 扩展需要定义 Vale CLI 路径：

"vale.valeCLI.path": "/path/to/vale"

== Creating pull requests for doc updates

通过针对 Quarkus 存储库的 @13 分支从你自己的 @15 中 @14 提交你向核心 Quarkus 文档提出的更改建议。

有关代码和文档的评论有不同的（但重叠的）参与者。为了简化协作评论，可以将对文档的更改隔离在单独的 PR 中，或者确保 PR 有一个单一的重点目标。例如：

创建一个单独的 PR，为一个扩展添加一个配置选项，并更新相关材料（操作方法、参考资料）来解释该更改。
为一组文档的相关更改创建一个单独的 PR；一些示例：更正术语的使用、更正重复出现的错误或将通用内容移动到共享的文件中。
如果存在大量的代码更改和文档更改，请为文档更改创建一个单独的 PR，并在问题描述中包含该关系。

GitHub 会自动向包含文档文件更改的 pull request 添加 @16 标签。

更多有关管理 pull request 的信息，请参阅 @17。

=== Automatic style checking on the PR diff

当创建一个或更新 PR 时，Vale linter 作业会自动运行。如果你的内容更新与 Quarkus 社区的关键样式或术语偏好不一致，则 diff 选项卡上的更新行中将附有 Vale 建议。为了确保你的内容获得批准，请修复 linter 错误、警告和建议。

我们欢迎你对 Quarkus 文档样式指南的反馈。

如果你不同意 Vale 结果，请添加黄色 PR 标签 @18。

== Previewing doc changes on the Quarkus website

将 PR 合并到 `main`后，并将分支与 Quarkus.io网站存储库同步，你可以在 Quarkus 网站的 Main branch (SNAPSHOT)文档页面上预览生成的构建输出。

`quarkus`存储库的 `main`分支每天在 GMT 时间上午 1 点同步，因此，在下次网站刷新发生之前，你无法在 Main branch (SNAPSHOT)上预览所做的更改。