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 のコンテンツタイプに固有のガイダンスにも従っている必要があります。
Content type | 以下を行う必要があります | 良い例e | 悪い例 |
---|---|---|---|
コンセプト |
|
Quarkus のセキュリティーと認証メカニズム |
Quarkus での反応型 SQL クライアントの発見 |
ハウツーガイド |
|
WebAuthn 認証による Quarkus アプリケーションのセキュリティー確保 |
Quarkus での WebAuthn 認証の適用 |
参考 |
|
Hibernate Reactive API の設定プロパティー |
Hibernate Reactive API 設定プロパティーを設定するためのリファレンスガイド |
チュートリアル |
|
クイックスタートの例を使用して、JVM モードの Quarkus アプリケーションを作成します。 |
アプリの作成 |
File conventions
ソースの場所
-
AsciiDoc files are in the
src/main/asciidoc
directory within thedocs
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), anddeprecated
. :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.
深い入れ子 (
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 マクロは、リンクを別ウィンドウで開くなどの関連性が考えられる 追加属性 もサポートしています。
The above source produces this link: AsciiDoc Syntax Quick Reference. |
クロスリファレンス
Quarkus のドキュメントは、いくつかの異なる環境でソースから構築されています。相互参照で属性を使用して、これらの環境全体でドキュメントを構築できるようにします。
属性e | Description |
---|---|
|
収集されたサンプルソースファイルを含むディレクトリーへの相対パス |
|
ドキュメントガイドのソース例への相対パス |
|
Relative path to documentation adoc files |
|
生成された設定ファイル |
|
イメージが格納されているディレクトリーへの相対パス |
|
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.
カテゴリー | Description |
---|---|
|
Support for other languages, namely Kotlin and Scala |
|
Quarkus runtime and ecosystem architecture |
|
Business automation integrations |
|
Integrations and support for cloud services |
|
コマンドラインアプリケーション |
|
Compatibility with other languages and frameworks |
|
Guidance and references to help you contribute to Quarkus. |
|
Information about how the Quarkus works |
|
Topics related to using data sources with Quarkus |
|
Getting started materials |
|
Support for integration extensions (Camel) |
|
Integrations with messaging systems like Kafka, AMQP, or RabbitMQ. |
|
その他 |
|
Everything related to native executables |
|
Extensions and integrations for runtime and application observability |
|
Extensions that support reactive technologies and techniques |
|
セキュリティ |
|
シリアル化 |
|
ツール |
|
ウェブ |
|
エクステンションの作成 |
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 ドキュメント変数
以下の変数は、時間の経過とともに変化する重要な情報を外部化しています。このような情報を参照するには、中括弧で囲まれた {}
内の変数を使用する必要があります。
使用する外部化変数の完全なリストを次の表に示します。
プロパティ名e | バリューe | Description |
---|---|---|
|
|
プロジェクトの現在のバージョン。 |
|
プロジェクトのホームページの場所。 |
|
|
プロジェクトの GitHub 組織の場所。 |
|
|
Quarkus GitHub の URL の共通ベース接頭辞。 |
|
|
Quarkus URL for |
|
|
メインソースアーカイブへの Quarkus URL。 |
|
|
ソースファイルを参照するために使用される、メインのブロブソースツリーへの Quarkus URL。 |
|
|
メインソースツリールートへの Quarkus URL。 |
|
|
Quarkus の課題ページへの URL。 |
|
|
Quarkus 用に配信されるコンテナーイメージのセットへの Quarkus URL。 |
|
|
チャットの URL |
|
|
メーリングリストに登録するために使用される電子メール。 |
|
|
メーリングリストのインデックスページです。 |
|
|
Quickstarts URL 共通ベースプレフィックス。 |
|
|
Quickstarts URL for |
|
|
|
メインソースアーカイブへのクイックスタート URL です。 |
|
メイン blob ソースツリーへのクイックスタート URL。 |
|
|
メインソースツリーのルートへのクイックスタートの URL。 |
|
|
|
使用する GraalVM の推奨バージョン。 |
|
|
The builder image tag of GraalVM to use e.g. |