Quarkus style and content guidelines

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

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.

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).

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:

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.

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.

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

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

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

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

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).

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.

Quarkus documentation is grouped into the following categories.

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:

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

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