为 Quarkus 文档做出贡献
请使用推荐的 diataxis 内容类型、步骤、工作流程和样式指导来为文档做贡献，以确保内容成功呈现在 Quarkus 网站门户上。
Quarkus 文档使用 AsciiDoc 标记。
先决条件
-
您拥有一个编辑器或 IDE，它提供 AsciiDoc 的语法高亮显示和预览，无论是原生支持还是通过插件。
-
您已查看以下 Quarkus 贡献者资源
-
Quarkus “贡献”指南的文档部分。
-
有关所需语法、首选样式和其他约定的Quarkus 样式和内容指南。
-
-
您手边有 AsciiDoc 语法参考。
找到 Quarkus 文档的源文件
-
AsciiDoc 文件位于 Quarkus GitHub 存储库的
docs模块中的src/main/asciidoc目录中。 -
Quarkus 文档模板位于 Quarkus GitHub 存储库的
docs模块中的src/main/asciidoc/_templates目录中。 -
配置文档从 Java 源代码文件中的 JavaDoc 注释生成。
-
Java、YAML 和其他源文件也可以被 AsciiDoc 文件引用。
-
Quarkus 文档菜单页面，也称为文档索引页面，源自 quarkusio.github.io 存储库。
在 AsciiDoc 中创建 Quarkus 内容
要确保您的内容正确显示在 Quarkus 文档主页上，请使用以下步骤
-
确定最适合您要贡献的内容的 Diataxis 内容类型。
为了帮助您做出决定，请参阅“关于 Quarkus 文档”页面上的标题和标题中的内容类型描述。 -
转到
src/main/asciidoc/_templates目录，并为您选择的内容类型复制相关的模板。请务必-
使用 `<category>-<titlekeyword>-<titlekeyword>.adoc` 的文件名语法。例如，
security-basic-authentication.adoc。 -
如果在文件名中包含 diataxis 类型（概念、操作指南、参考、教程）是有意义的，请这样做。例如，
telemetry-micrometer.adoc是一个参考，而telemetry-micrometer-tutorial.adoc是一个教程。 -
将文件保存到
quarkus存储库中的docs/src/main/asciidoc文件夹中。
-
-
设置最低要求的标题信息，以确保内容在网站门户和文档主页中正确呈现，如以下示例所示
[id="security-basic-authentication"] (1) = Secure a Quarkus application with basic authentication (2) include::_attributes.adoc[] (3) :diataxis-type: howto (4) :categories: security,web (5) (6)1 将 id值设置为与文件名相同，但不包含扩展名。2 有关如何为每种内容类型创建良好标题的信息，请参阅“Quarkus 样式和内容指南”页面上的标题和标题。 3 需要 _attributes.adoc包含，以确保属性得到解析并生成目录。4 指定 diataxis 类型： concept、howto、reference或tutorial。5 设置至少一个类别，以确保可以在 Quarkus 文档主页上找到该内容。有关 Quarkus 类别的列表，请参阅“Quarkus 样式和内容指南”页面上的文档属性和变量。 6 在所有文档属性之后和摘要之前插入一个空行。 确保文档 ID 和标题、属性包含 (
include::_attributes.adoc[]) 和其他文档属性声明 (:attribute:) 之间没有空行。 -
添加一个描述指南目的的摘要。
摘要的第一句话必须用少于 27 个单词来解释内容的价值和一些好处，因为这会自动显示在 Quarkus 指南主页上。摘要前后也必须有换行符。
有关最低标题要求的更多信息，请参阅“Quarkus 样式和内容指南”页面上的文档结构。
添加先决条件部分
对于操作指南和教程主题，请在摘要之后立即包含先决条件部分。声明先决条件明确了操作指南和教程内容的起点。即使对于知识渊博的用户来说，它们似乎很明显，也要包含它们。
.Prerequisites (1)
:prerequisites-time: 30 minutes (2)
include::{includes}/prerequisites.adoc[] (3)
* <an additional prerequisite> (4)| 1 | 先决条件的章节标题 |
| 2 | 可选：修改先决条件的属性 |
| 3 | prerequisites.adoc 文件的 include 语句 |
| 4 | 可选：属性未涵盖的附加先决条件 |
默认情况下，include::./_includes/prerequisites.adoc[] 插入以下 asciidoc
To complete this guide, you need:
* Roughly 15 minutes
* An IDE
* JDK 17+ installed with `JAVA_HOME` configured appropriately
* Apache Maven {maven-version}
* Optionally the xref:cli-tooling.adoc[Quarkus CLI] if you want to use it
* Optionally Mandrel or GraalVM installed and xref:building-native-image.adoc#configuring-graalvm[configured appropriately] if you want to build a native executable (or Docker if you use a native container build)可以选择通过在 include::./_includes/prerequisites.adoc[] 宏之前的行中插入以下属性来添加、删除或修改默认先决条件。
-
{prerequisites-time}: <分钟数>覆盖默认值 15 分钟。例如，{prerequisites-time}: 30添加* 大约 30 分钟。 -
{prerequisites-no-maven}删除* Apache Maven <maven 版本>。 -
{prerequisites-docker}添加* 一个可用的容器运行时（Docker 或 Podman）。 -
{prerequisites-docker-compose}添加Docker 和 Docker Compose 或 Podman，以及 Docker Compose。 -
{prerequisites-no-cli}删除* 可选的 Quarkus CLI（如果您想使用它）。 -
{prerequisites-no-graalvm}或{prerequisites-graalvm-mandatory}删除* 可选的 Mandrel 或 GraalVM 已安装并已正确配置（如果您想构建本机可执行文件）（或者如果您使用本机容器构建，则为 Docker）。 -
{prerequisites-graalvm-mandatory}添加* Mandrel 或 GraalVM 已安装并已正确配置。
有关这些属性的更多信息，请检查 docs/src/main/asciidoc/_includes/prerequisites.adoc 文件的内容。
停用和重定向现有的 Quarkus AsciiDoc 源文件
随着内容的演变，您可能希望将现有的一段 Quarkus 内容重组为一个或多个内容类型，并停用现有的 AsciiDoc 源文件。
如果您要停用或重命名已发布的 Quarkus AsciiDoc 源文件，请确保重组不会破坏现有书签和指向原始内容的链接。通过以下步骤在Quarkus.io 网站 GitHub 存储库中配置 URL 重定向
-
切换到
quarkusio/quarkusio.github.io存储库，然后打开_redirects/guides文件夹。 -
使用与您要停用的原始 AsciiDoc 源文件名匹配的文件名创建 Markdown 格式的重定向文件。
-
将以下内容添加到 Markdown 重定向文件中
--- permalink: /guides/<original_asciidoc_filename>/index.html (1) newUrl: /guides/<new_asciidoc_filename> (2) ---其中
1 您要停用的原始 AsciiDoc 源文件的名称，不包含 .adoc文件扩展名。2 您要重定向到的 AsciiDoc 源文件的名称，不包含 .adoc文件扩展名。
| 原始 AsciiDoc 源文件的名称 | 要重定向到的目标文件的名称 | 重定向文件 | 示例拉取请求 |
|---|---|---|---|
|
|
使用锚点交叉引用文件内和跨文件内容
锚点，也称为 ID，几乎可以在文档中的任何位置定义，包括在章节标题、离散标题、段落、图像、分隔块、内联短语等上。
这些锚点的标注功能因您调用本地 ID 还是来自另一个文件的 ID 而异，但锚定 ID 的创建方式保持不变。
创建一个锚定 ID
要为您想要引用的新文件或章节创建一个 ID，请按如下方式插入锚点 ID
-
使用小写字符。
-
用破折号字符分隔每个单词。
-
将 ID 括在双括号中。
在本节中，我们将使用在 2 级标题上方创建的锚点进行演示。
[[title-heading]]
== Title heading在同一文件中调用锚定 ID
要在同一文件中调用创建的锚点，请在 <<>> xref 宏中插入锚定 ID。
<<title-heading>>此宏创建一个 URL，其名称自动源自锚定标题、章节或表格。
请勿将 <<>> 格式与逐字标题或章节描述一起使用，例如 <<Title heading>>。 |
如果您想为您的 URL 指定一个非默认的标题，请指定锚定 ID 和所需名称，并用 , 分隔，不留空格。
<<title-heading,Title heading description that fits the context of your content>>从不同的文件中调用锚定 ID
要调用在不同文件中创建的锚点，请将锚点插入 xref 宏，并指定托管文件的完整名称和所需的锚定 ID。
xref:<other-file-name>.adoc#title-heading[Title heading]分解此示例，我们正在使用 xref 宏来引用另一个文件 (xref:<name-of-the-file>.adoc[Human-readable label])，并在文件名之后立即插入目标章节的锚点 ID (#title-heading)。
有关编写交叉引用的更多指南，包括推荐的路径属性，请参阅交叉引用。
预览和构建 Quarkus 文档
在您提交拉取请求之前，请使用以下构建方法之一预览 AsciiDoc 源的 HTML 输出
-
对于较小的文档更改，您可以使用 IDE 提供的 AsciiDoc 语法高亮显示和预览。
-
对于生成的配置文档的重大更改或更新，请在本地构建
docs模块并运行 Vale linter，如以下各节所述。
在本地构建 docs 模块
以下命令将构建 Quarkus 存储库中的所有模块（测试模块除外），并将它们安装到您的本地 Maven 存储库中，版本为 999-SNAPSHOT
./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|
当更新扩展配置时
|
使用 Vale 对文档更改进行 Lint
我们的构建使用 Vale 来检查文档的英文版本的语法、样式和单词用法。我们创建了自己的 Vale 样式规则集，以确保内容与首选的 Quarkus 样式指南保持一致。
|
容器化的 Vale
此方法需要一个可用的容器运行时（Docker 或 Podman）。
docs 模块有一个 JUnit 5 测试，它将在容器中运行 Vale linter（使用 Testcontainers）。它会验证 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 | 为 docs 模块的 src/main/asciidoc 目录中的所有 *.adoc 文件运行 Vale linter。在结果中包含建议、警告和错误。 |
| 2 | 为 docs 模块中任何已修改的 *.adoc 文件 (git status) 运行 Vale linter。在结果中包含警告和错误。 |
| 3 | 为与正则表达式（Java Pattern 语法）匹配的 *.adoc 文件运行 Vale linter。在结果中包含错误。 |
使用 Vale CLI
如果您安装了 Vale CLI，则必须指定配置文件和要扫描的目录或文件列表
# 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有关更多信息，请参阅 Vale CLI 手册。
Vale IDE 插件
Vale IDE 集成 需要安装 Vale CLI。
每个 IDE 集成都有其自己的配置要求。例如，Visual Studio Code IDE 扩展需要定义 Vale CLI 路径
"vale.valeCLI.path": "/path/to/vale"为文档更新创建拉取请求
代码和文档的审查有不同的（但重叠的）参与者。为了简化协作审查，要么将文档更改隔离在单独的 PR 中，要么确保 PR 具有单一的重点目的。例如
-
创建一个单一的 PR，用于添加扩展的配置选项并更新相关材料（操作指南、参考），以解释更改。
-
为一组文档的相关更改创建一个单一的 PR；一些示例：更正术语的使用、更正经常出现的错误或将通用内容移动到共享文件中。
-
如果存在大量的代码更改和文档更改，请为文档更改创建一个单独的 PR，并在问题描述中包含关系。
GitHub 会自动将 area/documentation 标签添加到包含文档文件更改的拉取请求中。
有关管理拉取请求的更多信息，请参阅Quarkus Committer 信息。
在 Quarkus 网站上预览文档更改
在您的 PR 合并到 main 并且分支与 Quarkus.io 网站存储库同步之后，您可以在 Quarkus 站点的 Main 分支 (SNAPSHOT) 文档页面上预览生成的构建输出。
|
|
