The English version of quarkus.io is the official project site. Translated sites are community supported on a best-effort basis.
Back to Guides

Quarkus style and content guidelines

Guidelines are provided to help you to contribute clear and consistent content that is also sourced in the required structure and composition of Quarkus documentation.

AsciiDoc syntax

Quarkus docs use AsciiDoc syntax. The following links provide background on AsciiDoc syntax and general conventions.

Language and grammar

Write clear, concise, and consistent technical information in US English. Write for a global audience with localization, translation, inclusivity, and diversity in mind. Try to use the following grammar styles:

Sentence length

Shorter sentences are much easier to read and translate. Try to use less than 32 words per sentence.

Website publication

Content from this repository is published to the Quarkus.io website.

  • Documentation built from the main branch is published nightly (main-SNAPSHOT).

  • Documentation for other branches is published at release time.

タイトルと見出し

コンテンツの種類に関わらず、メインタイトルや文書の見出しは次のようにすることを心がけてください:

  • 目標志向で、読者がなじみのある言葉やキーワードを利用する

  • 説明的で、フィラーワードを避ける

  • 検索エンジンでの検索性を最適化するため、1 行あたり 3〜12 ワード、50〜80 文字程度とする

  • 文章内で大文字を使うスタイルを採用する

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

Table 1. Quarkus のさまざまなコンテンツタイプに対応したタイトルガイダンス
Content type 以下を行う必要があります 良い例e 悪い例

コンセプト

  • コンセプトやトピックを示す名詞から始める

  • configure、install、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 …​"

  • 機能指向ではなく、行動指向またはタスク指向であること

  • Finish the implied sentence: "How to …​"

WebAuthn 認証による Quarkus アプリケーションのセキュリティー確保

Quarkus での WebAuthn 認証の適用

参考

  • 名詞句を使用して、文書の内容を簡潔に要約します

  • 'reference' という言葉を含まない

  • 暗示的な文を完成させる。"約…​"

Hibernate Reactive API の設定プロパティー

Hibernate Reactive API 設定プロパティーを設定するためのリファレンスガイド

チュートリアル

  • Start with an active verb in the imperative verb form, for example, "Create a …​" or "Secure a …​"

  • ユーザーがどのようなタスクを完了するのか、重要なトピックまたは実演されたアクティビティーに重点を置いて説明します。

  • 機能指向ではなく、行動指向またはタスク指向であること

  • 学習モードではユーザーのニーズに導かれること。

  • Finish the implied sentence: "In this tutorial, you will …​"

クイックスタートの例を使用して、JVM モードの Quarkus アプリケーションを作成します。

アプリの作成

File conventions

ソースの場所

  • AsciiDoc files are in the src/main/asciidoc 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.

出力先

設定リファレンス

Configuration reference documentation is generated from Javadoc comments discovered in MicroProfile Config source files. These generated files are in target/asciidoc/generated/config/ (from the project root).

AsciiDoc output to HTML

AsciiDoc processing creates HTML files in docs/target/generated-docs/.

テンプレート

Create new documentation files with the appropriate template for the content type:

コンセプト

Use 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 の使用

File names

Quarkus documentation uses a flat hierarchy.

The bulk of the file name should be some representation of its title. Use all lowercase letters, separate words with hyphens, and avoid symbols and special characters.

プレフィックス

Use a common prefix to group related documents. Documents related to writing and contributing to Quarkus docs share the doc- prefix, for example.

接尾辞

The file name should reflect the document type:

  • Concept documents should end in -concept.adoc

  • ハウツーガイドは -how.adoc で終わるべきである。

  • リファレンスは -reference.adoc で終わる必要があります。

  • チュートリアルは -tutorial.adoc で終わる必要があります。

Document structure

Document header

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

[id="doc-reference"] (1)
= Quarkus style and content guidelines (2)
\include::_attributes.adoc[] // <3> :categories: contributing (4)
1 Use the filename as the ID for the document.
2 Define the document title following guidance in [Titles and headings].
3 Include common document attributes.
4 Specify the relevant Categories (comma separated).

Other common document header attributes

:extension-status: preview

Use this attribute to flag special types of content. Valid values: experimental, preview, stable (not usually used), and 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.

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

アブストラクト (前文)

The first paragraph in the main body is treated as the abstract, also referred to as the preamble. Add a short description that helps your audience quickly find and understand the purpose and intent of the page. The first sentence of the abstract provides a summary and gets automatically added to the tile on the Quarkus guides homepage.

Try to write the abstract by using the following guidelines:

  • User oriented: Contains terms and keywords that are familiar to users.

  • Concise: Avoids self-referential expressions and filler words, for example:

    • "This document.."

    • "This tutorial…​"

    • "The following…​"

  • Brief: Is no more than three sentences long.

Ensure that the first sentence explains the value and some benefits of the content in 26 words or less.

If the first sentence is too long or can not 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 Other common document header attributes.

セマンティック改行

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

セクションの使用

セクションのタイトルは、タイトルケースではなく、センテンスケースで記述すること。

All documents should start with a Title (a = Level 0 heading), and should be broken into subsections where appropriate (== Level 1 to ====== Level 5) without skipping any levels.

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

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

  • Can the content be reorganized to make it simpler to consume?

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

リンク

In general, prefer url macros to bare or automatic links. Provide human-readable text for the link, especially if it is included in the middle of other text.

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

URL マクロは、リンクを別ウィンドウで開くなどの関連性が考えられる 追加属性 もサポートしています。

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

The above source produces this link: AsciiDoc Syntax Quick Reference.

クロスリファレンス

Quarkus のドキュメントは、いくつかの異なる環境でソースから構築されています。相互参照で属性を使用して、これらの環境全体でドキュメントを構築できるようにします。

Table 2. クロスリファレンスソース属性
属性e Description

{code-examples}

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

{doc-examples}

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

{doc-guides}

Relative path to documentation adoc files

{generated-dir}

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

{imagesdir}

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

{includes}

Relative path to directory containing partial/reusable content

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

クロスリファレンス例
xref:{doc-guides}/doc-concept.adoc[Quarkus Documentation concepts] (1)
1 相互参照は xref: で始まり、相互参照ソース属性 ({doc-guides})、および読みやすい説明を提供します: [Quarkus ドキュメントの概念]

リファレンスソースコード

ドキュメントにソースコードやサンプルを含めるには、さまざまな方法があります。

一番簡単なのは、このようにファイルに直接書き込むことです。

[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 will copy 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 define the simplified target file name to use when copying the file into the target/asciidoc/examples directory.

Content copied in this way is referenced by the {code-examples} source attribute. The literal string {{source}} in the source file, if present, will be replaced with the path of the source file in the copy.

マイクロメーター例
  • コピーされる元ファイルは

    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
  • Snippets from this source file are then referenced with the following path:

    {code-examples}/telemetry-micrometer-tutorial-example-resource.java.

  • ソースファイルには、以下のコメントが記載されています。

// ソース: {{source}}
  • コピーされたファイルには、代わりにこのコメントが含まれています。

// Source: integration-tests/micrometer-prometheus/src/main/java/io/quarkus/doc/micrometer/ExampleResource.java

Document attributes and variables

Categories

Quarkus documentation is grouped into the following categories.

Table 3. Categories
カテゴリー Description

alt-languages

Support for other languages, namely Kotlin and Scala

architecture

Quarkus runtime and ecosystem architecture

business-automation

Business automation integrations

cloud

Integrations and support for cloud services

command-line

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

compatibility

Compatibility with other languages and frameworks

contributing

Guidance and references to help you contribute to Quarkus.

core

Information about how the Quarkus works

data

Topics related to using data sources with Quarkus

getting-started

Getting started materials

integration

Support for integration extensions (Camel)

messaging

Integrations with messaging systems like Kafka, AMQP, or RabbitMQ.

miscellaneous

その他

native

Everything related to native executables

observability

Extensions and integrations for runtime and application observability

reactive

Extensions that support reactive technologies and techniques

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 4. 変数
プロパティ名e バリューe Description

{quarkus-version}

2.16.4.Final

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

{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

Quarkus URL for git clone referenced by the documentation.

{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/tree

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

Quickstarts URL for git clone referenced by the documentation.

{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}

22.3

使用する GraalVM の推奨バージョン。

{graalvm-flavor}

22.3-java17

The builder image tag of GraalVM to use e.g. 22.3-java17. Use a java17 version.