Quarkusスタイル・コンテンツガイドライン
ガイドラインは、Quarkusドキュメントに必要な構造や構成に基づいた、明確で一貫性のあるコンテンツを提供するためのものです。
ウェブサイト掲載
このリポジトリからのコンテンツは、 Quarkus.io ウェブサイト に公開されます。
-
mainブランチからビルドされたドキュメントは毎晩公開されます(main-SNAPSHOT)。
-
その他のブランチのドキュメントは、リリース時に公開されます。
タイトルと見出し
コンテンツの種類に関わらず、メインタイトルや文書の見出しは次のようにすることを心がけてください:
-
目標志向で、読者がなじみのある言葉やキーワードを利用する
-
説明的で、フィラーワードを避ける
-
検索エンジンでの検索性を最適化するため、1 行あたり 3〜12 ワード、50〜80 文字程度とする
-
文章内で大文字を使うスタイルを採用する
タイトルと見出しは、次の表に示すように、Quarkus のコンテンツタイプに固有のガイダンスにも従っている必要があります。
| Content type | 以下を行う必要があります | 良い例 | 悪い例 |
|---|---|---|---|
コンセプト |
|
Quarkus のセキュリティーと認証メカニズム |
Quarkus でのリアクティブSQL クライアントの発見 |
ハウツーガイド |
|
WebAuthn 認証による Quarkus アプリケーションのセキュリティー確保 |
Quarkus での WebAuthn 認証の適用 |
参考 |
|
Hibernate Reactive API の設定プロパティー |
Hibernate Reactive API 設定プロパティーを設定するためのリファレンスガイド |
チュートリアル |
|
クイックスタートの例を使用して、JVM モードの Quarkus アプリケーションを作成します。 |
アプリの作成 |
ファイル規約
ソースの場所
-
AsciiDoc files are in the
src/main/asciidocdirectory within thedocsmodule of the Quarkus GitHub repository. -
設定ドキュメントは、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-というプレフィックスを共有します。 - 接尾辞
-
Use a suffix that reflects the document type (optional):
-
-concept.adocfor concept documents -
-howto.adocfor how-to guides -
-reference.adocfor references -
-tutorial.adocfor tutorials
-
ドキュメント構造
Use the Quarkus templates to ensure that your content is consistent with the preferred Quarkus documentation structure and style.
ドキュメントヘッダー
各ドキュメントは、ドキュメントスコープ属性のヘッダを定義すべきです。最低限，各ドキュメントは，idとタイトルを定義し，共通属性( _attributes.adoc )を含むべきです。
[id="doc-reference"] (1)
= Quarkus style and content guidelines (2)
\include::_attributes.adoc[] (3)
:diataxis-type: {type} (4)
:categories: contributing (5)| 1 | ファイル名をドキュメントのIDとして使用します。 |
| 2 | Define the document title following guidance in タイトルと見出し. |
| 3 | 共通のドキュメント属性をインクルードする。 |
| 4 | Specify the diataxis type: concept, howto, reference, or tutorial. |
| 5 | Specify the relevant カテゴリー (comma separated). |
その他の共通ドキュメントヘッダー属性
:extension-status: preview-
この属性は、特別なタイプのコンテンツにフラグを立てるために使用します。有効な値:
experimentalpreview,stable(通常は使用しない) ,deprecated. :summary: <text>-
Use the summary to provide a concise (26 words or less) description of the document. The value of this attribute is used in tiles or other descriptions on the website and is not required in newer diataxis-styled docs, as outlined in 要約 (前文). If not present, the first sentence of the abstract is automatically used to generate the tile summary.
| 文書スコープの属性を扱うときは、空白に注意してください。文書ヘッダーは最初の空行で終わります。 |
要約 (前文)
本文の最初の段落は要約として扱われ、プリアンブルとも呼ばれます。閲覧者がページの目的や意図をすぐに見つけ、理解できるような短い説明を追加します。要約の最初の文はサマリーとなり、 Quarkusガイドのホームページ のタイルに自動的に追加されます。
以下のガイドラインを参考にして、要約を書くようにしてください:
-
ユーザーオリエンテッドである: ユーザーにとって身近な用語やキーワードが含まれている。
-
簡潔である: 例えば、自己言及的な表現、フィラーワードを避ける。例:
-
"This document.."
-
"This tutorial…"
-
"The following…"
-
-
Brief: Is no more than three sentences long.
|
最初のセンテンスで、コンテンツの価値やいくつかのメリットを26文字以内で説明しているようにして下さい。 |
If the first sentence is too long or cannot be simplified to fit on the website tile, you can define a :summary: attribute in the document header attributes to serve that purpose.
For more information, see その他の共通ドキュメントヘッダー属性.
セマンティック改行
段落、リスト、および表のテキストは、[1] をレビューしやすいように細かく分割する必要があります。各文の終わりで新しい行を開始し、句間の自然な区切りで文自体を分割します。
セクション
セクションのタイトルは、タイトル・ケースではなく、センテンス・ケースで記述してください。
Start your document with a title, which in AsciiDoc is defined as a = Level 0 heading.
Where appropriate, divide your content into subsections, which in AsciiDoc are defined as == Level 1 to ====== Level 5.
Do not skip any levels.
|
深い入れ子 (
See Quarkus documentation content types for more information about content types and organization. |
リンク
一般的に、素のリンクや自動リンクよりも urlマクロ の方が望ましいです。特に、リンクが他のテキストの途中に含まれている場合は、人間が読めるテキストを用意してください。
|
属性を持つ URL マクロリンク
URLマクロは、リンクを別ウィンドウで開くなど、関連しそうな 追加属性 もサポートしています。 上記のソースはこの AsciiDoc構文クイックリファレンス を作成します。 |
クロスリファレンス
Quarkus documentation is built from source in a few different environments.
クロスリファレンスソース属性
We use attributes in our cross-references to ensure our docs can be built across these environments.
| 属性 | 説明 |
|---|---|
|
収集されたサンプルソースファイルを含むディレクトリーへの相対パス |
|
ドキュメントガイドのソース例への相対パス |
|
生成された設定ファイル |
|
イメージが格納されているディレクトリーへの相対パス |
|
部分的な/再利用可能なコンテンツを含むディレクトリーへの相対パス |
コンテンツを相互参照する場合は、常にドキュメント間の xref: 構文を使用し、人間が判読できるラベルをリンクに付けてください。
xref:doc-concept.adoc[Quarkus Documentation concepts] (1)| 1 | The cross-reference starts with xref:, and provides a readable description: [Quarkus Documentation concepts]. |
ファイル内およびファイル間ナビゲーションのためのアンカー
-
アンカーIDを作成するには、小文字を使用し、各単語を
-で区切り、以下の例のように[[]]でIDを囲んでください。[[title-heading]] == Title heading -
同じファイルに作成されたアンカーを呼び出すには、
<<>>xrefマクロにアンカーIDを挿入してください。<<title-heading>> -
カスタムURLキャプションの例でアンカーを作成するには、アンカーIDと希望する名前を空白なしで
,で区切って指定します。<<title-heading,Title heading description that fits the context of your content>>[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]For more details about anchored IDs, see the Cross-reference in-file and cross-file content by using anchors section of the "Contribute to Quarkus documentation" guide.
Cross-reference phrasing
For consistency and context clarity, use the following guidelines for constructing your cross-reference phrases:
-
Provide a direct hyperlink to the section, using the
xrefguidance in the previous section. -
Specify the full title of the section and use sentence case.
-
Add the definite article “the” before the section title and specify “section” directly after the title.
-
Add the definite article “the” and “Quarkus” before the title of the guide, unless the word “Quarkus" is already in the title.
-
Insert the title of the guide between double quotations and specify “guide” directly after the title.
-
If the context is needed, lead with the phrase:
-
"For more information about …"
-
| Correct | Incorrect |
|---|---|
For more information, see the Configuring the ValidatorFactory section of the Quarkus "Validation with Hibernate Validator" guide. |
For more information, see the 'Configuring the ValidatorFactory' section of the VALIDATION WITH HIBERNATE VALIDATOR guide. |
For more information, see the Generating a cache key with CacheKeyGenerator section of the Quarkus "Application Data Caching" guide. |
For more information, see Generating a cache key with CacheKeyGenerator. |
For more information, see the PKCE-related section of the Quarkus "OpenID Connect (OIDC) Authorization Code Flow Mechanism" guide. |
For more information, see OpenID Connect (OIDC) Authorization Code Flow Mechanism. |
リファレンスソースコード
There are many ways to include source code and examples in the documentation.
一番簡単なのは、このようにファイルに直接書き込むことです。
[source,java]
----
System.out.println("Hello, World!");
----In documents like tutorials, you may want to reference source code that is built and tested regularly.
The Quarkus documentation build copies source files enumerated in *-examples/yaml files into a flattened structure in the target/asciidoc/examples directory (from the project root).
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}} が存在する場合は、コピー先のソースファイルのパスに置き換えられます。
-
コピーされる元ファイル:
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のドキュメントは、以下のカテゴリーに分類されています。
| カテゴリー | 説明 |
|---|---|
|
他の言語、すなわちKotlinとScalaのサポート |
|
Quarkusのランタイムとエコシステム・アーキテクチャ |
|
ビジネスオートメーション統合 |
|
クラウドサービスとの統合・サポート |
|
コマンドラインアプリケーション |
|
他の言語やフレームワークとの互換性 |
|
Quarkusに貢献するためのガイダンスとリファレンス。 |
|
Quarkus の仕組みに関する情報 |
|
Quarkusでのデータソースの使用に関連するトピック |
|
入門用資料 |
|
インテグレーションエクステンション（Camel）のサポート |
|
Kafka、AMQP、RabbitMQのようなメッセージングシステムとの統合。 |
|
その他 |
|
ネイティブ実行可能ファイルに関する全て |
|
ランタイムとアプリケーションのobservabilityを高めるためのエクステンションと統合 |
|
セキュリティ |
|
シリアル化 |
|
ツール |
|
ウェブ |
|
エクステンションの作成 |
Tag your content to improve findability by adding at least one category to the categories attribute line in the document header. To add multiple categories, use comma-separated values. For example:
:categories: contributing, dataQuarkus ドキュメント変数
以下の変数は、時間の経過とともに変化する重要な情報を外部化しています。このような情報を参照するには、中括弧で囲まれた {} 内の変数を使用する必要があります。
使用する外部化変数の完全なリストを次の表に示します。
| プロパティ名 | 値 | 説明 |
|---|---|---|
|
|
プロジェクトの現在のバージョン。 |
|
プロジェクトのホームページの場所。 |
|
|
プロジェクトの GitHub 組織の場所。 |
|
|
Quarkus GitHub の URL の共通ベース接頭辞。 |
|
|
ドキュメントで参照されている |
|
|
メインソースアーカイブへの Quarkus URL。 |
|
|
ソースファイルを参照するために使用される、メインのブロブソースツリーへの Quarkus URL。 |
|
|
メインソースツリールートへの Quarkus URL。 |
|
|
Quarkus の課題ページへの URL。 |
|
|
Quarkus 用に配信されるコンテナーイメージのセットへの Quarkus URL。 |
|
|
チャットの URL |
|
|
メーリングリストに登録するために使用される電子メール。 |
|
|
メーリングリストのインデックスページです。 |
|
|
Quickstarts URL 共通ベースプレフィックス。 |
|
|
ドキュメントで参照されている |
|
|
|
メインソースアーカイブへのクイックスタート URL です。 |
|
メイン blob ソースツリーへのクイックスタート URL。 |
|
|
メインソースツリーのルートへのクイックスタートの URL。 |
|
|
|
使用する GraalVM の推奨バージョン。 |
|
|
The builder image tag of GraalVM to use e.g. |
