The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.
一覧に戻る

Quarkusドキュメントの寄稿方法

QuarkusのWebサイトポータルでコンテンツが正常にレンダリングされるように、推奨されるコンテンツタイプ、ステップ、ワークフロー、スタイルガイダンスを使用して、ドキュメントに貢献します。

Quarkusのドキュメントには、 AsciiDoc のマークアップが使用されています。

前提条件

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.

  • 設定ドキュメントは、Javaソースファイル内のJavaDocコメントから生成されます。

  • JavaやYAMLなどのソースファイルをAsciiDocのファイルから 参照 することも可能です。

  • Quarkusのドキュメント メニューページは、doc indexページとも呼ばれ、 quarkusio.github.io リポジトリにソースがあります。

QuarkusのコンテンツをAsciiDocで作成

Quarkusドキュメントホームページ にコンテンツが正しく表示されるようにするには、次のステップを使用します:

  1. 投稿するコンテンツに最適な Diataxis のコンテンツタイプを決めましょう。

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

  2. src/main/asciidoc/_templates ディレクトリに移動し、選択したコンテンツタイプに対応するテンプレートのコピーを作成します。必ず、以下のようにしてください:

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

    • quarkus リポジトリの docs/src/main/asciidoc フォルダに保存してください。

  3. 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:

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

    Ensure there are no blank lines between the document id and title, the attribute include (include::_attributes.adoc[]) and the declaration of other document attributes(:attribute:).

  4. Add an abstract that describes the purpose of the guide.

    Quarkusガイド のホームページに自動的に表示されるため、要約の最初の文は、コンテンツの価値と何らかの利益を27単語以内で説明する必要があります。また、要約の前後で改行する必要があります。

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

By default, include::./_includes/prerequisites.adoc[] inserts the following 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)
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.

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

既存のQuarkus AsciiDocソースファイルの削除とリダイレクト

コンテンツの進化に伴い、既存のQuarkusコンテンツを1つまたは複数のコンテンツタイプに再編成し、既存のAsciiDocソースファイルを破棄したい場合があります。

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:

  1. Switch to the quarkusio/quarkusio.github.io repository, and open the _redirects/guides folder.

  2. 破棄したい元のAsciiDocのソースファイル名と一致するファイル名のリダイレクトファイルをMarkdown形式で作成します。

  3. Markdownリダイレクトファイルに、以下の内容を追加します:

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

    何処に

    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. 例
元のAsciiDocソースファイル名 リダイレクト先となるファイル名 Redirection file プルリクエストの例

security-getting-started

security-overview-concept

security-getting-started.md

PR #1579

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

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.

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

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

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を挿入してください。

Inter-document anchored ID call example
<<title-heading>>

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

[Title heading] のように、逐語的な見出しやセクションの説明に <<>> 形式を使用しないでください。

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

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]

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.

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

Quarkusドキュメントのプレビューとビルド

Pull Request を送信する前に、以下のビルド方法のいずれかを使用して、AsciiDoc ソースの HTML 出力をプレビューしてください:

  • ちょっとしたドキュメントの変更であれば、IDEが提供するAsciiDocのシンタックスハイライトとプレビューを利用することができます。

  • 生成された設定ドキュメントの大幅な変更や更新は、 docs モジュールをローカルでビルドし、以下のセクションで説明するように Vale linter を実行してください。

docs モジュールをローカルでビルド

以下は、Quarkusリポジトリにあるすべてのモジュール（テストモジュールを除く）をビルドし、`999-SNAPSHOT`バージョンでローカルmavenリポジトリにインストールします:

./mvnw -DquicklyDocs

-DquicklyDocs の実行は以下を生成します:

  • target/asciidoc/generated/config/ ディレクトリに自動生成の設定プロパティを記述したAsciiDoc（ adoc ファイル）

  • docs/target/generated-docs/ ディレクトリにAsciiDoc出力（ html ファイル）。

  • 全ドキュメント個別のメタデータを含むYAML ( `docs/target/indexByFile.yaml `) とドキュメントタイプ別にグループ化したメタデータを含むYAML ( `target/indexByType.yaml `)。

  • ファイル別にメタデータのエラーをリストアップするYAMLファイル( `docs/target/errorsByFile.yaml `)と、エラーの種類別にメタデータのエラーをリストアップするYAMLファイル( `docs/target/errorsByType.yaml `)

変更をPRで提出し、レビューを受ける前に、結果の出力をレビューし、問題があれば修正を行ってください。

変更を加えると、特に docs モジュールを再構築して、生成された HTML を更新できます。

./mvnw -f docs clean install

エクステンションの設定を更新する場合:

  1. エクステンションのJavadocを改訂する

  2. target/asciidoc/generated/config/ にコンテンツを生成するためにエクステンションをビルドする

  3. docs モジュールをビルドして、レンダリング結果を確認する。

Valeによるドキュメント変更の性的解析

我々は Vale を使用して、英語版ドキュメントの文法、スタイル、単語の使用状況をチェックしています。独自のValeスタイルルールセットを作成し、コンテンツがQuarkusの推奨スタイルガイドラインに沿うようにしました。

  • ValeのQuarkusの設定は、 docs/.vale.ini にあります。

  • Quarkusのスタイルルールは、 docs/.vale/styles ディレクトリにあるYAMLフォーマットです。

コンテナ化されたVale

この方法では、動作するコンテナランタイム（Dockerまたは Podman ）が必要です。

docs モジュールには、JUnit 5 テストがあり、コンテナ内で Vale リンターを実行します（ 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 Manual をご覧ください。

Vale IDE プラグイン

Vale 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"

ドキュメント更新のためのプルリクエストの作成

Quarkus リポジトリの main ブランチに対して、 プルリクエストの作成 を行い、自身の リポジトリのフォーク から Quarkus のコアドキュメントに変更案を提出します。

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:

  • エクステンションの設定オプションを追加し、変更を説明するために関連資料 (ハウツー、リファレンス) を更新する単一の PR を作成します。

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

  • 広範囲なコード変更とドキュメント変更がある場合、ドキュメント変更のために別のPRを作成し、Issueの説明にその関係性を含めてください。

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

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

PR diffの自動スタイルチェック

PRが作成または更新されると、Valeのリンタージョブが自動的に実行されます。コンテンツの更新がQuarkusコミュニティの主要なスタイルや用語の好みと一致しない場合、diffタブの更新行にValeの推奨事項の注釈が付きます。コンテンツが承認されるように、リンターのエラー、警告、および提案を修正してください。

Quarkusのドキュメントスタイルガイドラインに関するご意見をお待ちしております。

Valeの結果に同意できない場合は、黄色のPRラベル needs-vale-rule-tweak を付けてください。

QuarkusのWebサイトでdocの変更点をプレビューする

PRが main にマージされ、ブランチが Quarkus.io ウェブサイトのリポジトリと同期されると、Quarkusサイトの Main branch (SNAPSHOT) ドキュメントページで、結果のビルド出力をプレビューすることができます。

quarkus リポジトリの main ブランチは、毎日グリニッジ標準時の午前1時に同期されるため、次のサイト更新が行われるまで、 Main ブランチ（SNAPSHOT ）での変更をプレビューすることはできません。

関連コンテンツ

同一トピック

Quarkusはオープンです。このプロジェクトのすべての依存関係は、Apache Software License 2.0 または互換性のあるライセンスのもとで利用可能です。

このウェブサイトはJekyll で構築され、GitHub Pages にホストされ、完全にオープンソースです。改善したい場合は、ウェブサイトをフォークし、修正してみせてください。

ナビゲーション
フォローする
ヘルプ
言語
Quarkusはコミュニティプロジェクトで構成されています
CC by 3.0 | Privacy Policy Sponsored by