フィードバックを送信
Liferay Style Guide
ご覧のページは、お客様の利便性のために一部機械翻訳されています。また、ドキュメントは頻繁に更新が加えられており、翻訳は未完成の部分が含まれることをご了承ください。最新情報は都度公開されておりますため、必ず英語版をご参照ください。翻訳に問題がある場合は、 こちら までご連絡ください。

書式設定

この記事では、製品ドキュメントとコースの両方に適用される書式設定オプション（テキストの強調表示、コード、リスト、表、見出し、画像、注意書き、ファイル名、前付け、プレースホルダー）について説明します。 声、言い回し、構成原則については、 コアスタイル を参照してください。 コンテンツタイプ固有のルールについては、 ドキュメントスタイル または コーススタイル を参照してください。

記事の命名規則

ファイル名は小文字のケバブケースで、記事のH1タイトルと一致します。 メッセージボードの使用 というタイトルの記事には、 using-message-boards.md というファイル名があります。 記事のタイトルを [トピック] の紹介 にしないでください ( コアスタイル も参照)。

前書き

前付けキーは、 taxonomy-category-names内の値とともにアルファベット順に並べ替えますが、 toc はアルファベット順ではなく、読む順序で並べ替えます。 （レンダリングされたページは分類カテゴリを自動的に再編成し、アルファベット順に並べ替えるため、ソースコードの順序はあくまでも執筆上の整合性を保つためのものです。）

典型的な記事の冒頭部分：

---
showChildrenCards: false
taxonomy-category-names:
  - Liferay PaaS
  - Liferay SaaS
  - Liferay Self-Hosted
toc:
  - ./getting-started.md
  - ./configuring-the-system.md
  - ./managing-users.md
uuid: 12345678-1234-1234-1234-123456789abc
---

改行

段落は1行に収まるようにしてください。動的なワードラップを使用し、80列で改行しないでください。 段落は改行を2回入れて区切ってください。

太字

太字は控えめに使用してください。 読者の目は太字に引きつけられるため、太字が多すぎると効果が薄れてしまう。 見出しはすべてレンダリング時に太字になるため、本文を不必要に太字にすることは避けてください。

以下の場合は太字を使用してください。

フォーム内のフィールド名: フォームの説明時には、フィールド名を太字にしてコロンを付けます。

名前: ユーザー名を入力してください。

住所: ユーザーの住所を入力してください。

定義ラベル: 定義する用語を太字にします ( 定義 を参照)。

サブセクションのコールアウト: 本文セクションに、独自の見出しを必要としない複数のラベル付きサブ項目が含まれている場合。

セクションの最後にフォーム要素のリストを記述してはいけません。

斜体

コンセプト紹介

初めて概念を紹介する際は、その用語をイタリック体で表記する。 以降は斜体にしないでください。

Liferay DXP は、多くの OSGi モジュール で構成されています。 モジュールとは、それ自体で完結するアプリケーションにも、既存の機能の拡張機能にもなり得る、機能の一部を指します。

UI要素

UI要素の名前（メニュー、ページ、タブ、ボタン、フィールドなど）は、インターフェースに表示されるとおり大文字で表記されます。 斜体にするかどうかは、読者がそのステップでその要素に対して何らかの操作を行うかどうかによって決まります。

読者にUI上の何かをクリックするように指示する場合は、要素名を斜体にする。

続行するには、 保存 をクリックしてください。

クリック指示のないUI要素を参照する場合は、大文字で表記しますが、斜体にはしません。

ボタンをクリックすると、設定ページが表示されます。

2つのルールを組み合わせて、どのUI要素がクリックを受け取るかを明確にします。

設定ページで、 追加 ボタンをクリックします。

指示を受ける要素は斜体で表示され、周囲のコンテキスト要素はすべて大文字で表示されます。

コード

3つのバッククォートと言語識別子でコードブロックをオフセットします。

```java
[Java code here]
```

以下の行をシングルバッククォートで囲むと、コードとしてインラインで表示されます。

  • ファイル名
  • クラス
  • データベーステーブル
  • 変数
  • フォルダーとディレクトリ
  • CLIコマンドとフラグ
  • 環境変数名
  • 構成プロパティのキーと値
  • APIエンドポイントパス
  • 技術的な文脈におけるポート番号（8080）

定義

定義は、定義する用語を太字で示し、その後にコロンを付ける段落です。 それらは決して箇条書きにはならない。

定義: 用語の意味を説明する文。

用語: 意味を定義する必要があるオブジェクト、通常は名詞。

定義においては、定義対象の用語を決して使用してはならない。

一覧

手順を順序立てて示す場合や、順序が重要な場合は、番号付きリストを使用してください。 順序のない項目には箇条書きを使用してください。 箇条書きの項目は、順序に意味がない場合はアルファベット順に並べ替えてください。

項目を列挙する前にその数を明記する場合は、番号付きリストを使用してください。

サイトを作成する方法は3つあります。

  1. サイトを作成する。

  2. まず組織を作成し、次にその組織のウェブサイトを作成します。

  3. 新しいポータルインスタンスを作成し、その中にサイトを作成します。

個数が明記されていない場合は、箇条書きで構いません。

ボタンをクリックすると、以下のオプションが表示されます。

  • 参照
  • 編集する
  • 削除

継続文リスト

導入部分がそれ自体で完全な文ではなく、各リスト項目が文を完成させる場合は、コロンを省略し、項目によって文を完成させるようにしてください。 導入部分を完全な節に強制すると、 コロン規則 を満たすためにフィラー ("the following", "these prerequisites") が追加されるだけの場合、これが正しい選択です。

ArgoCDドメインを構成する前に、

  • デプロイされたCNE環境
  • 登録済みドメイン（例： argocd.mydomain.com）

各項目は導入部分（「CNE環境が展開されている必要があります」）を完成させるため、コロンや間投詞は必要ありません。

番号付きリスト形式

すべての項目に 1. の番号を付けます。 （自動採番） 行間はシングルスペースでもダブルスペースでも構いません。各項目が複数の段落を含む場合、または複数行にわたる場合は、項目間に空白行を入れてください。

1. This is a numbered list. When this paragraph ends, line up the second paragraph with the beginning of the first.

   This is the second paragraph in the first item.

1. This is the second item.

1. This is the third item.

ステップの紹介

手順の説明に文の断片を使用しないでください。 断片的な文章は、読みにくい宙ぶらりんの構造を残してしまう。 最初のステップに直接進むか、簡潔で完全な文脈を示す文を使用してください。

悪い（断片的な導入部分）：

## Editing Fields

To edit fields,

1. Step one

良い（直接的な手順）：

## Editing Fields

1. Click the _Edit_ button.

1. Enter a name...

また、以下の方法もお勧めです（手順の前に簡潔な完全な文章を添える）：

## Editing Fields

Fields can be edited at any time without affecting published content.

1. Click the _Edit_ button.

1. Enter a name...

テーブル

| header 1 | header 2 | header 3 |
| :--- | :--- | :--- |
| cell 1 | cell 2 | cell 3 |
ヘッダー1ヘッダー2ヘッダー3
細胞1細胞2細胞3

比較表

公開ページと非公開ページなど、アイテム間の機能を比較する場合は、チェックマーク付きの表を使用してください。

| Behavior | Public Pages | Private Pages |
| --- | --- | --- |
| Visible to unauthenticated users | ✔ |  |
| Viewing requires Login and Site Membership |  | ✔ |
| Distinct URL pattern | ✔ | ✔ |

表の説明

説明文は名詞句でも完全な文でも構いませんが、1つの表の中で両方を混在させてはいけません。表内の一貫性が、どちらのスタイルを選ぶかよりも重要です。

  • 名詞句の説明文には末尾にピリオドは付けません（リスト項目と同じ慣例です）。
  • 完全な文による説明にはピリオドが必要です。

セルに完全な文が必要な場合（例えば、複数の文を含むセルなど）、その列のすべてのセルに完全な文を記入してください。

名詞句の説明：

項目説明
名前UIに表示されるオブジェクト名
範囲応募作品の入手可能性

完全な文章による説明：

項目説明
名前オブジェクト名はUIに表示されます。
範囲この範囲内のエントリーが利用可能です。

見出し

見出しを使って論理的な階層構造を作り、読者が記事をざっと見て、目的の箇所へ移動できるようにしましょう。

  • H1: 記事のタイトル。 記事1つにつき、正確に1つ。 文書内の最初の見出し。 記事のタイトルメタデータと一致する必要があります。
  • H2: 記事内の主要なセクション。 ほとんどの記事はH2セクションのみで構成されています。
  • H3: 主要セクションに、それぞれ独自の見出しが必要な 2 つ以上の異なるサブトピックが含まれている場合のサブセクション。
  • H4: 控えめに使用してください。 H3セクション自体に、圧縮できない個別のサブカテゴリが含まれている場合に限ります。

H5とH6は完全に避けてください。 もしそれらに手を伸ばしてしまうようなら、記事の構成を見直す必要があるか、あるいはその内容は別の記事に分けるべきでしょう。

レベルを飛ばさないでください（例えば、H2からH4にジャンプするなど）。 スクリーンリーダーや自動化ツールは、一貫した階層構造に依存している。

変数とプレースホルダー

プレースホルダーを角括弧で囲むことで、コード（通常は山括弧で囲まれる）と区別できます。

デフォルトの HSQL データベースは [Liferay Home]/data に保存されます。

画像

ストレージと命名規則

アイコンなど、複数の記事で再利用される画像もあります。 各製品の英語ドキュメントセクションのルートには、共有の 画像 フォルダがあります。

共有イメージの命名規則として、以下の接頭辞のいずれかを使用してください。

  • icon-
  • button-
  • menu-

記事ごとの画像は、記事の横にある ./images/ サブディレクトリに格納されます。 それらを連番で命名します: 01.png、 02.pngなど。 スクリーンショットを追加、削除、または並べ替える場合は、番号を振り直して連続性を保ち、記事内で画像が表示される順序と一致するようにしてください。

画像キャプチャ

アイコン画像を20×20ピクセルでキャプチャしてください。 スクリーンショットは、ページに適した幅にリサイズしてください。一般的には、幅800ピクセル以下にしてください。 （HiDPIディスプレイをサポートするには、2倍の解像度でキャプチャし、レンダリング時にレンダリングソフトが対応している場合はダウンスケールしてください。）

代替テキスト

すべての画像には代替テキストが必要です。 代替テキストは単なるラベルではありません。それは、画像の外見だけでなく、その目的を説明する完全な文である必要があります。

悪い例: Liferay セットアップウィザード。

良い点： Liferay セットアップウィザードには、データベースの種類と接続を選択するためのフィールドがあります。

説明が必要な複雑な画像（図、ER図、アーキテクチャ図など）については、2段階のアプローチを採用してください。まず、画像を識別するための簡潔な代替テキスト（alt属性）を記述し、次に、記事本文に詳細なテキストによる説明を記述します。

例： コンテンツエントリが下書きから承認されるまでの進行状況を示すワークフロー図。 詳細については、以下のテキストを参照してください。

純粋に装飾的な画像（バナー、情報を追加しないバッジなど）の場合は、空の alt 属性を使用します（alt=""）。 alt属性を完全に省略しないでください。多くのスクリーンリーダーはファイル名を読み上げるようにフォールバックしますが（例： banner-v2.png）、これは邪魔になります。

画像に、周囲の記事には含まれていないテキストが含まれている場合は、alt属性にそのテキストを正確に含めてください。

画像キャプション

Markdownはネイティブの画像キャプションをサポートしていません。 代替テキストはキャプションの役割を果たします。表示されている内容とそれがなぜ重要なのかを説明する、完全で分かりやすい文章で記述してください。 代替テキストの内容を周囲の文章に重複して記載しないでください。

スクリーンショット内のUI要素の強調表示

ボックスの強調表示や数値注釈を使用して、読者の視線を特定のUI要素に誘導します。

UI要素を囲むように枠線を描画して、注釈を付けます。

数値注釈には、以下の本文中のそれらの注釈の定義を添える必要があります。

数値注釈を使用する場合は、画像の下のテキストで各数値が何を表しているかを定義してください。

コース固有のマークアップ規則（色、スクリーンショットのフレーミング基準、Lexicon Icons Figma ソース）については、 コーススタイル を参照してください。

図

読者が複雑な概念を理解しやすいように、図を追加してください。例えば、機能同士の関係性、データの流れ、あるいはUIのスクリーンショットでは関係性が伝わらないような事柄などです。 図は次のような場合に適切です。

  • 一般的な概念または方法論を紹介する。
  • UI表現が存在しないバックエンドプロセス、アーキテクチャ、またはデータフローを視覚化する。
  • UIは、統合されたコンポーネントと重複するコンポーネントを明確に区別していない。
  • システムコンポーネント間またはデータ構造間の関係を視覚化する。
  • 複数の機能、モデル、またはシナリオを並べて比較する。

既存のコース図の完全なリストについては、 ブランドポータル を参照してください。

ビデオ

YouTubeに動画をアップロードし、YouTubeトークンを使って参照します。

<iframe allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen frameborder="0" height="315" src="https://www.youtube.com/embed/x7fm_nCZ0sY" title="YouTube video player" width="560"></iframe>

警告

読者の注意を引くために、忠告を用いる。 それらは重要なことを強調するために、本体から際立って配置されている。 使いすぎは禁物です。注意書きが頻繁に出てくると、読者は読み飛ばしてしまうからです。

4種類の忠告にはそれぞれ特定の目的がある。

  • 注: メインコンテンツを補足する背景情報またはコンテキスト。 読者は、その部分を飛ばしても手順に支障はありません。
  • ヒント: 読者の体験を向上させるショートカット、ベストプラクティス、または分かりにくいアプローチ。
  • 重要: 読者がタスクを正しく完了するために必要な情報。 手順を省略すると、手順が失敗したり、予期しない結果が生じたりする可能性がある場合に使用してください。
  • 警告: 無視すると、データ損失、セキュリティ侵害、不可逆的な変更、またはその他の深刻な損害を引き起こす可能性のある情報です。

使用量

!!! tip "[text here goes in title bar]"
    This is a tip. This is a link in a [tip](https://www.liferay.com). Markdown formatting is supported in an admonition.

警告構文の詳細は、Flexmark Wiki を参照してください。