Contribute to Quarkus documentation

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

Contribute to the documentation by using the recommended diataxis content types, steps, workflow, and style guidance to ensure the content successfully renders on the Quarkus website portal.

Quarkus 文档使用 AsciiDoc 标记。

Quarkus docs use AsciiDoc markup.

Prerequisites

You have an editor or IDE that provides syntax highlighting and previews for AsciiDoc, either natively or with a plugin.
You have reviewed the following Quarkus contributor resources:
- The Documentation section of the Quarkus "Contributing" guide.
- The Quarkus style and content guidelines for the required syntax, preferred style, and other conventions.
- The Quarkus documentation content types.
You have the AsciiDoc syntax reference nearby.

Locate the source files for Quarkus docs

AsciiDoc files are in the src/main/asciidoc directory within the docs module of the Quarkus GitHub repository.
The Quarkus doc templates are located in the src/main/asciidoc/_templates 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.
The Quarkus documentation menu page, also known as the doc index page, is sourced in the quarkusio.github.io repository.

Create Quarkus content in AsciiDoc

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

To ensure that your content shows up correctly on the Quarkus documentation home page, use the following steps:

Decide on a Diataxis content type that best fits the content that you are contributing.

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

To help you decide, see the content type descriptions in Titles and headings on the "About Quarkus documentation" page.

Go to the src/main/asciidoc/_templates directory, and make a copy of the relevant template for the content type you have chosen. Be sure to:
- Use the filename syntax of`<category>-<titlekeyword>-<titlekeyword>.adoc`. For example, security-basic-authentication.adoc.
- Include the diataxis type (concept, howto, reference, tutorial) in the file name if it makes sense to do so. For example, telemetry-micrometer.adoc is a reference, and telemetry-micrometer-tutorial.adoc is a tutorial.
- Save the file to the docs/src/main/asciidoc folder in the quarkus repository.
Set the minimum required header information to ensure that the content renders correctly in the website portal and on the documentation home page, as outlined in the following example:[source, asciidoc]

[id="security-basic-authentication"] 1
= Secure a Quarkus application with basic authentication 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-contribute-docs-howto.adoc 3
:diataxis-type: howto 4
:categories: security,web 5
6

1	Set the `id` value to be the same as the file name but without the extension.
2	For information about how to create a good title for each content type, see Titles and headings on the "Quarkus style and content guidelines" page.
3	The `_attributes.adoc` include is required to ensure that attributes get resolved and the table of contents is generated.
4	Specify the diataxis type: `concept`, `howto`, `reference`, or `tutorial`.
5	Set at least one category to ensure that the content is findable on the Quarkus documentation home page. For a list of Quarkus categories, see Document attributes and variables on the "Quarkus style and content guidelines" page.
6	Insert a blank line after all document attributes and before the abstract.

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

Ensure there are no blank lines between the document id and title, the attribute include (include::_attributes.adoc[] :iokays-category: quarkus :iokays-path: modules/ROOT/pages/doc-contribute-docs-howto.adoc) and the declaration of other document attributes(:attribute:).

Add an abstract that describes the purpose of the guide.====== 抽象部分的第一句话必须在不超过 27 个单词内解释内容的价值和一些好处，因为这会自动显示在 Quarkus guides homepage。在摘要之前和之后还必须有一个换行符。

The first sentence of the abstract must explain the value and some benefit of the content in less than 27 words because this automatically displays on the Quarkus guides homepage. There must also be a line break before and after the abstract.

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

For more information about the minimum header requirements, see Document structure on the "Quarkus style and content guidelines" page.

== Add a prerequisites section

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

For how-to and tutorial topics, include a prerequisites section just after the abstract. Declaring prerequisites clarifies the starting place for both how-to and tutorial content. Include them even though they might seem obvious to knowledgeable users.

An example prerequisite with callout explanations

.Prerequisites 1

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

1	Section heading for the prerequisites
2	Optional: An attribute that modifies the prerequisites
3	An include statement for the `prerequisites.adoc` file
4	Optional: An additional prerequisite not covered by the attributes

The default prerequisites

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

The default prerequisites

By default, include::{includes}/prerequisites.adoc[] inserts the following asciidoc:

Unresolved directive in doc-contribute-docs-howto.adoc - include::{includes}/prerequisites.adoc[]

Using attributes to modify the prerequisites

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

Using attributes to modify the prerequisites

Optionally, you can add, remove, or modify the default prerequisites by inserting the following attributes on the line before the include::{includes}/prerequisites.adoc[] macro.

{prerequisites-time}: <number of minutes> overrides the default value of 15 minutes. For example, {prerequisites-time}: 30 adds * Roughly 30 minutes.
{prerequisites-no-maven} removes * Apache Maven <maven version>.
{prerequisites-docker} adds * A working container runtime (Docker or Podman).
{prerequisites-docker-compose} adds Docker and Docker Compose or Podman, and Docker Compose.
{prerequisites-no-cli} removes * Optionally the Quarkus CLI if you want to use it.
{prerequisites-no-graalvm} or {prerequisites-graalvm-mandatory} remove * 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} adds * Mandrel or GraalVM installed and configured appropriately.

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

For more information about these attributes, inspect the content of the docs/src/main/asciidoc/_includes/prerequisites.adoc file.

== Retire and redirect an existing Quarkus AsciiDoc source file

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

As content evolves, you might want to restructure an existing piece of Quarkus content into one or more content types and retire the existing AsciiDoc source file.

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

If you are retiring or renaming a published Quarkus AsciiDoc source file, ensure that the restructure does not break existing bookmarks and links to the original content. Configure a URL redirect in the Quarkus.io Website GitHub repository by using the following steps:

Switch to the quarkusio/quarkusio.github.io repository, and open the _redirects/guides folder.
Create a redirection file in Markdown format with a filename that matches the original AsciiDoc source filename that you want to retire.
Add the following contents to the Markdown redirection file:[source, markdown]

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

其中：

Where:

1	The name of the original AsciiDoc source file that you are retiring, without the `.adoc` file extension.
2	The name of the AsciiDoc source file that you want to redirect to, without the `.adoc` file extension.

Table 1. Example
Name of original AsciiDoc source file	Name of target file to redirect to	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）可在文档中的几乎任何地方定义，包括章节标题、独立标题、段落、图片、分隔块、内联句子等。

An anchor, also called an ID, can be defined almost anywhere in the document, including on a section title, discrete heading, paragraph, image, delimited block, inline phrase, etc.

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

The callout functions for these anchors vary based on whether you call a local ID or the ID from another file, but the anchored ID creation remains the same.

=== Create an anchored ID

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

To create an ID for a new file or a section to which you want to refer, insert the anchor ID as follows:

Use lower-case characters.
Separate each word with a dash character.
Enclose the ID in double square brackets.

Anchored ID creation example

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

Anchored ID creation example

In this section, we will use an anchor created above the level-2 heading for demonstration purposes.

[[title-heading]]
== Title heading

=== Call an anchored ID in the same file

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

To call an anchor created in the same file, insert the anchored ID in a <<>> xref macro.

Inter-document anchored ID call example

<<title-heading>>

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

This macro creates an URL with a name automatically sourced from the anchored heading, section, or table.

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

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

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

When you want to specify a non-default caption for your URL, specify the anchored ID and desired name separated by , without white space.

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。

To call an anchor created in a different file, insert the anchor to an xref macro and specify the full name of the hosting file and the desired anchored 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)。

Breaking this example apart, we are using the xref macro to refer to another file (xref:<name-of-the-file>.adoc[Human-readable label]) and inserting the anchor ID for the target section (#title-heading) just after the file name.

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

For more guidelines on writing cross-references, including the recommended path attributes, see Cross-references.

== Preview and build Quarkus documentation

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

Before you submit a pull request, preview the HTML output of your AsciiDoc source by using one of the following build methods:

For minor documentation changes, you can use the AsciiDoc syntax highlighting and preview provided by your IDE.
For significant changes or updates to generated configuration documentation, build the docs module locally and run the Vale linter as outlined in the following sections.

=== Build the docs module locally

Unresolved directive in doc-contribute-docs-howto.adoc - include::{includes}/compile-quarkus-quickly.adoc[]

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

Running -DquicklyDocs produces:

Generated AsciiDoc (adoc files) describing configuration properties in the target/asciidoc/generated/config/ directory.
AsciiDoc output (html files) in the docs/target/generated-docs/ directory.
YAML files containing metadata for all documents individually (docs/target/indexByFile.yaml) and grouped by document type (target/indexByType.yaml).
YAML files that list metadata errors by file (docs/target/errorsByFile.yaml) and by error type (docs/target/errorsByType.yaml)

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

Review the resulting output and fix any issues before you submit your changes in a PR for review.

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

As you make changes, you can rebuild the docs module specifically to update the generated HTML:

./mvnw -f docs clean install

更新扩展配置时：

When updating extension configuration:

Revise the Javadoc in the extension
Build the extension to regenerate content in target/asciidoc/generated/config/
Build the docs module to view the rendered results.

== Lint documentation changes with Vale

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

Our builds use Vale to check grammar, style, and word usage in the English versions of our documents. We created our own Vale style ruleset to ensure that content aligns with the preferred Quarkus style guidelines.

The Quarkus configuration for Vale is in docs/.vale.ini.
The Quarkus style rules are in YAML format in the docs/.vale/styles directory.

=== Containerized Vale

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

This approach requires a working container runtime (Docker or Podman).

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

The docs module has a JUnit 5 test that will run the Vale linter in a container (using Testcontainers). It verifies both Quarkus document metadata and Vale style rules.

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

Run the test in one of the following ways:

./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	Run the Vale linter for all `*.adoc` files in the `src/main/asciidoc` directory of the `docs` module. Include suggestions, warnings, and errors in the results.
2	Run the Vale linter for any modified `*.adoc` files in the `docs` module (`git status`). Include warnings and errors in the results.
3	Run the Vale linter for `*.adoc` files that match the regular expression (Java Pattern syntax). Include errors in the results.

=== Use the Vale CLI

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

If you install the Vale CLI, you must specify the configuration file and the directory or list of files to scan:

# 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。

For more information, see the Vale CLI Manual.

=== Vale IDE plugins

@12 要求安装 Vale CLI。

Vale IDE integrations require the Vale CLI to be installed.

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

Each IDE integration has its own configuration requirements. The Visual Studio Code IDE extension, for example, requires a definition of the Vale CLI path:

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

== Creating pull requests for doc updates

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

Submit your proposed changes to the core Quarkus docs by creating a pull request against the main branch of the Quarkus repository from your own repository fork.

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

Reviews for code and documentation have different (but overlapping) participants. To simplify collaborative review, either isolate changes to docs in separate PRs or ensure that a PR has a single focused purpose. For example:

Create a single PR that adds a configuration option for an extension and updates related materials (how-to, reference) to explain the change.
Create a single PR for related changes to a group of documents; some examples: Correcting the usage of a term, correcting a recurring error, or moving common content into a shared file.
If there are extensive code changes and documentation changes, create a separate PR for the documentation changes and include the relationship in the issue description.

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

GitHub automatically adds the area/documentation label to pull requests that contain changes to documentation files.

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

For more information about managing pull requests, see Information for Quarkus Committers.

=== Automatic style checking on the PR diff

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

The Vale linter job automatically runs when a PR is created or updated. If your content updates do not align with the key style or terminology preferences of the Quarkus community, the updated line on the diff tab gets annotated with the Vale recommendations. To ensure that your content gets approved, fix the linter errors, warnings, and suggestions.

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

We welcome your feedback on the Quarkus documentation style guidelines.

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

If you disagree with the Vale results, add the yellow PR label needs-vale-rule-tweak.

== Previewing doc changes on the Quarkus website

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

After your PR is merged to main and the branch is synchronized with the Quarkus.io website repository, you can preview the resulting build output on the Main branch (SNAPSHOT) documentation page of the Quarkus site.

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

The main branch of the quarkus repository is synchronized daily at 1 AM GMT, so you cannot preview your changes on the Main branch (SNAPSHOT) until after the next site refresh occurs.