The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.
このページを編集

Quarkusスタイル・コンテンツガイドライン

ガイドラインは、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 files are in the src/main/asciidoc directory within the docs module 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.adoc for concept documents

  • -howto.adoc for how-to guides

  • -reference.adoc for references

  • -tutorial.adoc for 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

この属性は、特別なタイプのコンテンツにフラグを立てるために使用します。有効な値: experimental preview , 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.

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

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

  • コンテンツをより消費しやすいように再設定できないか?

See Quarkus documentation content types for more information about content types and organization.

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

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

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

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

上記のソースはこの 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.

Table 2. クロスリファレンスソース属性
属性 説明

{code-examples}

収集されたサンプルソースファイルを含むディレクトリーへの相対パス

{doc-examples}

ドキュメントガイドのソース例への相対パス

{generated-dir}

生成された設定ファイル *.adoc への相対パス

{imagesdir}

イメージが格納されているディレクトリーへの相対パス

{includes}

部分的な/再利用可能なコンテンツを含むディレクトリーへの相対パス

コンテンツを相互参照する場合は、常にドキュメント間の 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 xref guidance 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 …​"

Table 3. Correct and incorrect cross-reference phrases
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}} が存在する場合は、コピー先のソースファイルのパスに置き換えられます。

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のドキュメントは、以下のカテゴリーに分類されています。

Table 4. カテゴリー
カテゴリー 説明

alt-languages

他の言語、すなわちKotlinとScalaのサポート

architecture

Quarkusのランタイムとエコシステム・アーキテクチャ

business-automation

ビジネスオートメーション統合

cloud

クラウドサービスとの統合・サポート

command-line

コマンドラインアプリケーション

compatibility

他の言語やフレームワークとの互換性

contributing

Quarkusに貢献するためのガイダンスとリファレンス。

core

Quarkus の仕組みに関する情報

data

Quarkusでのデータソースの使用に関連するトピック

getting-started

入門用資料

integration

インテグレーションエクステンション(Camel)のサポート

messaging

Kafka、AMQP、RabbitMQのようなメッセージングシステムとの統合。

miscellaneous

その他

native

ネイティブ実行可能ファイルに関する全て

observability

ランタイムとアプリケーションのobservabilityを高めるためのエクステンションと統合

security

セキュリティ

serialization

シリアル化

tooling

ツール

web

ウェブ

writing-extensions

エクステンションの作成

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, data

Quarkus ドキュメント変数

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

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

Table 5. 変数
プロパティ名 説明

{quarkus-version}

3.17.2

プロジェクトの現在のバージョン。

{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

The builder image tag of GraalVM to use e.g. jdk-17.

関連コンテンツ