Back to Guides

Version:

このページを編集

Quarkus style and content guidelines

ガイドラインは、Quarkusドキュメントに必要な構造や構成に基づいた、明確で一貫性のあるコンテンツを提供するためのものです。

Asciidoc 構文

Quarkusのドキュメントでは、AsciiDoc構文が使用されています。以下のリンクは、AsciiDocの構文と一般的な規約に関する背景を説明しています。

言語・文法

明確で簡潔、かつ一貫性のある技術情報を米国英語で書いて下さい。ローカライゼーション、翻訳、包括性、多様性を考慮し、グローバルな読者のために書いて下さい。以下の文法スタイルを使用するように心がけて下さい：

センテンスの長さ

短い文章は読みやすく、翻訳しやすいです。一文に使う単語数は32語以下になるように心がけましょう。

ウェブサイト掲載

このリポジトリからのコンテンツは、 Quarkus.io ウェブサイトに公開されます。

mainブランチからビルドされたドキュメントは毎晩公開されます(main-SNAPSHOT)。
その他のブランチのドキュメントは、リリース時に公開されます。

タイトルと見出し

コンテンツの種類に関わらず、メインタイトルや文書の見出しは必ず付けてください。

目標志向で、聴衆の言葉やキーワードを利用する
説明的で、フィラーワードを避ける
検索エンジンでの検索性を最適化するため、1 行あたり 3〜12 ワード、50〜80 文字程度とします
文例大文字スタイルでは

タイトルと見出しは、次の表に示すように、Quarkus のコンテンツタイプに固有のガイダンスにも従っている必要があります。

Table 1. Quarkus のさまざまなコンテンツタイプに対応したタイトルガイダンス
Content type	以下を行う必要があります	良い例	悪い例
コンセプト	Start with a noun that names the concept or topic Never start with an active verb, for example, an action word like configure, install, or start Finish the implied sentence: "Understanding …"	Quarkus のセキュリティーと認証メカニズム	Quarkus での反応型 SQL クライアントの発見
ハウツーガイド	Start with an active verb in the imperative verb form, for example, "Create a …" or "Secure a …" Be action-oriented or task-oriented, rather than feature-oriented Finish the implied sentence: "How to …"	WebAuthn 認証による Quarkus アプリケーションのセキュリティー確保	Quarkus での WebAuthn 認証の適用
参考	Use a noun phrase to concisely summarize the content of the document Not include the word 'reference' Finish the implied sentence: "About …"	Hibernate Reactive API の設定プロパティー	Hibernate Reactive API 設定プロパティーを設定するためのリファレンスガイド
チュートリアル	Start with an active verb in the imperative verb form, for example, "Create a …" or "Secure a …" State what task the user will complete, with emphasis on the key topic or demonstrated activity Be action-oriented or task-oriented, rather than feature-oriented Be led by the needs of the user in learning mode. Finish the implied sentence: "In this tutorial, you will …"	クイックスタートの例を使用して、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ファイルを作成します。

テンプレート

コンテンツタイプに適したテンプレートで、新しいドキュメントファイルを作成してください:

コンセプト: docs/src/main/asciidoc/_templates/template-concept.adoc を使用します
ハウツーガイド: docs/src/main/asciidoc/_templates/template-howto.adoc の使用
参考: docs/src/main/asciidoc/_templates/template-reference.adoc の使用
チュートリアル: docs/src/main/asciidoc/_templates/template-tutorial.adoc の使用

ファイル名

Quarkus ドキュメントはフラットなヒエラルキーを使用します。

ファイル名の大部分は、そのタイトルを何らかの形で表現する必要があります。すべて小文字で、単語はハイフンで区切り、記号や特殊文字は避けてください。

プレフィックス

関連ドキュメントをグループ化するには、共通の接頭辞を使用します。例えば、Quarkusドキュメントの執筆や貢献に関連するドキュメントは、 doc- というプレフィックスを共有します。

接尾辞

ドキュメントの種類を反映する接尾辞を使用します (オプション)。

概念関連のドキュメント用の -concept.adoc
ハウツーガイド用の -howto.adoc
リファレンス用の -reference.adoc
チュートリアル用の -tutorial.adoc

ドキュメント構造

Quarkus テンプレートを使用して、推奨される Quarkus ドキュメントの構造とスタイルと、コンテンツが一致していることを確認します。

ドキュメントヘッダー

Each document should define a header for document-scoped attributes. Minimally, each document should define an id and a title, include common attributes (_attributes.adoc), and set the diataxis type.

[id="doc-reference"] (1)
= Quarkus style and content guidelines (2)
\include::_attributes.adoc[] (3)
:diataxis-type: {type} (4)

1	ファイル名をドキュメントのIDとして使用します。
2	ドキュメントのタイトルをタイトルと見出しガイダンスに従って定義します。
3	共通のドキュメント属性をインクルードする。
4	`concept`、 `howto`、 `reference`、または `tutorial` から diataxis のタイプを指定します。

その他の共通ドキュメントヘッダー属性

:extension-status: preview: この属性は、特別なタイプのコンテンツにフラグを立てるために使用します。有効な値: experimental preview , stable (通常は使用しない) , deprecated .
概要: サマリーは、ドキュメントの簡潔な（26語以下の）説明を提供するために使用します。この属性の値は、ウェブサイト上のタイルやその他の説明で使用され、アブストラクト (前文) で概説したように、より新しい diataxis スタイルのドキュメントでは必要ありません。存在しない場合、要約の最初の文がタイルのサマリーを生成するために自動的に使用されます。

Take care with whitespace when working with document-scoped attributes. The document header ends with the first blank line.

アブストラクト (前文)

本文の最初の段落は要約として扱われ、プリアンブルとも呼ばれます。閲覧者がページの目的や意図をすぐに見つけ、理解できるような短い説明を追加します。要約の最初の文はサマリーとなり、 Quarkusガイドのホームページのタイルに自動的に追加されます。

以下のガイドラインを参考にして、要約を書くようにしてください:

ユーザーオリエンテッドである: ユーザーにとって身近な用語やキーワードが含まれている。
簡潔である: 例えば、自己言及的な表現、フィラーワードを避ける。例:
- "This document.."
- "This tutorial…"
- "The following…"
概要: 3 文以内にします。

最初のセンテンスで、コンテンツの価値やいくつかのメリットを26文字以内で説明しているようにして下さい。

最初の文が長すぎる場合、または Web サイトのタイルに収まらないほど簡略化できない場合は、ドキュメントヘッダー属性に :summary: 属性を定義して、その目的を果たすことができます。詳細は、その他の共通ドキュメントヘッダー属性を参照してください。

セマンティック改行

段落、リスト、および表のテキストは、^[1] をレビューしやすいように細かく分割する必要があります。各文の終わりで新しい行を開始し、句間の自然な区切りで文自体を分割します。

セクション

セクションのタイトルは、タイトル・ケースではなく、センテンス・ケースで記述してください。

ドキュメントはタイトルから始めます。AsciiDoc では、タイトルは = Level 0 見出しとして定義されています。必要に応じて、コンテンツをサブセクションに分割します。AsciiDoc では、サブセクションは == Level 1 から ====== Level 5 として定義されています。どのレベルもスキップしないでください。

深い入れ子 ( ====== Level 4 、 ====== Level 5 ) は、可能な限り避ける必要があります。深くネストされたセクションになってしまった場合は、次のことを考慮してください。

この情報は適切な場所にありますか? 例えば、これがリファレンスであれば、このコンテンツの一部をコンセプトドキュメントやハウツーガイドに移すべきでしょうか?
コンテンツをより消費しやすいように再設定できないか?

コンテンツの種類と構成の詳細は、Quarkusドキュメントのコンテンツの種類を参照してください。

リンク

一般的に、素のリンクや自動リンクよりも urlマクロの方が望ましいです。特に、リンクが他のテキストの途中に含まれている場合は、人間が読めるテキストを用意してください。

属性を持つ URL マクロリンク

URLマクロは、リンクを別ウィンドウで開くなど、関連しそうな追加属性もサポートしています。

https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/[AsciiDoc Syntax Quick Reference,window=_blank,opts=nofollow]

上記のソースはこの AsciiDoc構文クイックリファレンスを作成します。

クロスリファレンス

Quarkus のドキュメントは、いくつかの異なる環境でソースから構築されています。

クロスリファレンスソース属性

クロスリファレンスで属性を使用することで、これらの環境でドキュメントを構築できるようになります。

Table 2. クロスリファレンスソース属性
属性	説明
`{code-examples}`	収集されたサンプルソースファイルを含むディレクトリーへの相対パス
`{doc-examples}`	ドキュメントガイドのソース例への相対パス
`{generated-dir}`	生成された設定ファイル `*.adoc` への相対パス。
`{imagesdir}`	イメージが格納されているディレクトリーへの相対パス
`{includes}`	部分的な/再利用可能なコンテンツを含むディレクトリーへの相対パス

コンテンツを相互参照する場合は、常にドキュメント間の xref: 構文を使用し、人間が判読できるラベルをリンクに付けてください。

Cross-reference example

xref:doc-concept.adoc[Quarkus Documentation concepts] (1)

1	クロスリファレンスは `xref:` で始まり、 `[Quarkus ドキュメントの概念]` など、読みやすい説明を提供します。

ファイル内およびファイル間ナビゲーションのためのアンカー

アンカーIDを作成するには、小文字を使用し、各単語を - で区切り、以下の例のように [[]] でIDを囲んでください。
```
[[title-heading]]
== Title heading
```
同じファイルに作成されたアンカーを呼び出すには、 <<>> xref マクロにアンカーIDを挿入してください。
```
<<title-heading>>
```
カスタムURLキャプションの例でアンカーを作成するには、アンカーIDと希望する名前を空白なしで , で区切って指定します。
```
<<title-heading,Title heading description that fits the context of your content>>
```
Do not use the <<>> format with the verbatim heading or section description, such as <<Title heading>>.
別のファイルからアンカー付き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 を指定します。
ガイドのタイトルに Quarkus という単語がすでに含まれていない限り、ガイドのタイトルの前に定冠詞 the と Quarkus を追加します。
ガイドのタイトルを二重引用符で囲み、タイトルの直後にガイドと指定します。
文脈が必要な場合は、次のフレーズで始めます。
- "For more information about …"

Table 3. 正しいクロスリファレンスの文章および誤ったクロスリファレンスの文章
正しい	間違い
詳細は、Quarkus の「Hibernate Validator を使用した検証」ガイドの ValidatorFactory の設定セクションを参照してください。	詳細は、VALIDATION WITH 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` ディレクトリにファイルをコピーする際に使用する簡略化されたターゲットファイル名を定義します。

この方法でコピーされたコンテンツは、 ../_generated-doc/latest/examples source属性で参照されます。ソースファイル内にリテラル文字列 {{source}} が存在する場合は、コピー先のソースファイルのパスに置き換えられます。

Micrometer例

コピーされる元ファイルは

integration-tests/micrometer-prometheus/src/main/java/documentation/example/telemetry/micrometer/tutorial/ExampleResource.java
docs で使いたいターゲットファイル名は。

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 documentation categories are maintained in docs/src/main/resources/categories.yaml. When you add, rename, or remove a guide, update that file so the guide appears in the appropriate category or subcategory on the documentation website.

Do not add or keep :categories: attributes in guide headers. The docs build injects generated category metadata into copied target sources from categories.yaml. The build also checks that every guide is listed in categories.yaml and that every listed guide exists.

Quarkus ドキュメント変数

以下の変数は、時間の経過とともに変化する重要な情報を外部化しています。このような情報を参照するには、中括弧で囲まれた {} 内の変数を使用する必要があります。

使用する外部化変数の完全なリストを次の表に示します。

Table 4. 変数
プロパティ名	値	説明
`{quarkus-version}`	`3.39.4`	プロジェクトの現在のバージョン。
`{quarkus-home-url}`	`https://quarkus.io`	プロジェクトのホームページの場所。
`{quarkus-org-url}`	`https://github.com/quarkusio`	プロジェクトの GitHub 組織の場所。
`{quarkus-base-url}`	`https://github.com/quarkusio/quarkus`	Quarkus GitHub の URL の共通ベース接頭辞。
`{quarkus-clone-url}`	`https://github.com/quarkusio/quarkus.git`	ドキュメントで参照されている `git clone` の Quarkus URL。
`{quarkus-archive-url}`	`https://github.com/quarkusio/quarkus/archive/main.zip`	メインソースアーカイブへの Quarkus URL。
`{quarkus-blob-url}`	`https://github.com/quarkusio/quarkus/blob/main`	ソースファイルを参照するために使用される、メインのブロブソースツリーへの Quarkus URL。
`{quarkus-tree-url}`	`https://github.com/quarkusio/quarkus/tree/main`	メインソースツリールートへの Quarkus URL。
`{quarkus-issues-url}`	`https://github.com/quarkusio/quarkus/issues`	Quarkus の課題ページへの URL。
`{quarkus-images-url}`	`https://github.com/quarkusio/quarkus-images`	Quarkus 用に配信されるコンテナーイメージのセットへの Quarkus URL。
`{quarkus-chat-url}`	`https://quarkusio.zulipchat.com`	チャットの URL
`{quarkus-mailing-list-subscription-email}`	`quarkus-dev+subscribe@googlegroups.com`	メーリングリストに登録するために使用される電子メール。
`{quarkus-mailing-list-index}`	`https://groups.google.com/d/forum/quarkus-dev`	メーリングリストのインデックスページです。
`{quickstarts-base-url}`	`https://github.com/quarkusio/quarkus-quickstarts`	Quickstarts URL 共通ベースプレフィックス。
`{quickstarts-clone-url}`	`https://github.com/quarkusio/quarkus-quickstarts.git`	ドキュメントで参照されている `git clone` の Quickstarts URL。
`{quickstarts-archive-url}`	`https://github.com/quarkusio/quarkus-quickstarts/archive/main.zip`	メインソースアーカイブへのクイックスタート URL です。
`{quickstarts-blob-url}`	`https://github.com/quarkusio/quarkus-quickstarts/blob/main`	メイン blob ソースツリーへのクイックスタート URL。
`{quickstarts-tree-url}`	`https://github.com/quarkusio/quarkus-quickstarts/tree/main`	メインソースツリーのルートへのクイックスタートの URL。
`{graalvm-version}`	`for JDK 21`	使用する GraalVM の推奨バージョン。
`{graalvm-flavor}`	`jdk-21`	使用する GraalVM のビルダーイメージタグ (例: `jdk-17`)。

1. Rhodes, B. Semantic Linefeeds. https://rhodesmill.org/brandon/2012/one-sentence-per-line/