書式設定
この記事では、製品ドキュメントとコースの両方に適用される書式設定オプション（テキストの強調表示、コード、リスト、表、見出し、画像、注意書き、ファイル名、前付け、プレースホルダー）について説明します。 声、言い回し、構成原則については、 コアスタイル を参照してください。 コンテンツタイプ固有のルールについては、 ドキュメントスタイル または コーススタイル を参照してください。
記事の命名規則
ファイル名は小文字のケバブケースで、記事の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 は、断片を小文字にする シカゴ マニュアル オブ スタイル とはここで異なっています。
ラベル自体のケースの作り方は、ラベルの種類によって異なります。
- 何か に名前を付けるラベル — ドキュメントの一部、コースの成果物、視覚要素、定義される用語 — はタイトルケースになります: 学習目標:、 知識チェック:、 矢印:、 定義:。
- ガイダンス一覧の中で通常見られる、基準や指示を示すラベルは、文頭大文字表記のままにします：レッスンベース：、概念重視：、直接的かつ明確：、締切日を合わせる：。
重要なのは、ラベルがどこに位置するかではなく、そのラベルが果たす役割である。名前は肩書きであり、基準はタイトルケースで表記すると不自然に聞こえるフレーズである。
2つのラベルは、どちらのルールにも当てはまらない。 UI フィールド ラベル を再現するラベルは、インターフェースが名称を決定する権限を持つため、製品独自の表記になります。 ラベル引用ルールテキストは引用された語句を保持します。 「we」や「let's」は使用しない ラベル（ Core Style 内）はその一例です。
斜体
コンセプト紹介
初めて概念を紹介する際は、その用語をイタリック体で表記する。 以降は斜体にしないでください。
Liferay DXP は、多くの OSGi モジュール で構成されています。 モジュールとは、それ自体で完結するアプリケーションにも、既存の機能の拡張機能にもなり得る、機能の一部を指します。
UI要素
UI要素の名前（メニュー、ページ、タブ、ボタン、フィールドなど）は、インターフェースに表示されるとおり大文字で表記されます。 斜体にするかどうかは、読者がその段階でその要素に対して何らかの操作を行うかどうかによって決まります。
読者にUI上の何かをクリックするように指示する場合は、要素名を斜体にする。
続行するには、 保存 をクリックしてください。
クリック指示のないUI要素を参照する場合は、大文字で表記しますが、斜体にはしません。
ボタンをクリックすると、設定ページが表示されます。
2つのルールを組み合わせて、どのUI要素がクリックを受け取るかを明確にします。
設定ページで、 追加 ボタンをクリックします。
指示を受ける要素は斜体で表示され、周囲のコンテキスト要素はすべて大文字で表示されます。
ナビゲーションパス
読者をネストされた UI (メニューのクリックやナビゲーション手順のシーケンス) に導くには、手順をスペースで区切られた右矢印エンティティ → で結合します。 → エンティティのみを使用し、リテラルの Unicode 矢印や --> のような ASCII 形式は使用しないでください。 読者が実行する各ステップを、 UI要素ごとに斜体にする。
コントロール パネル → インスタンス設定 → 共有 に移動します。
パス内のステップがアイコンのみのコントロールである場合、そのステップを インラインアイコン の規則でフォーマットします。
グローバルメニュー (
) → コントロールパネル → 設定 を開きます。
コード
3つのバッククォートと言語識別子でコードブロックをオフセットします。
```java
[ここにJavaコード]
```
以下の行をシングルバッククォートで囲むと、コードとしてインラインで表示されます。
- ファイル名
- クラス
- データベーステーブル
- 変数
- フォルダーとディレクトリ
- CLIコマンドとフラグ
- 環境変数名
- 構成プロパティのキーと値
- APIエンドポイントパス
- 技術的な文脈におけるポート番号（
8080）
定義
定義は、定義する用語を太字で示し、その後にコロンを付ける段落です。 それらは決して箇条書きにはならない。
定義: 用語の意味を説明する記述。
用語: 意味を定義する必要があるオブジェクト、通常は名詞。
定義においては、定義対象の用語を決して使用してはならない。
リスト
手順を順序立てて示す場合や、順序が重要な場合は、番号付きリストを使用してください。 順序のない項目には箇条書きを使用してください。 箇条書きの項目は、順序に意味がない場合はアルファベット順に並べ替えてください。
項目を列挙する前にその数を明記する場合は、番号付きリストを使用してください。
サイトを作成する方法は3つあります。
サイトを作成する。
まず組織を作成し、次にその組織のウェブサイトを作成します。
新しいポータルインスタンスを作成し、その中にサイトを作成します。
個数が明記されていない場合は、箇条書きで構いません。
ボタンをクリックすると、以下のオプションが表示されます。
- ビュー
- 編集
- 消去
継続文リスト
導入部分がそれ自体で完全な文ではなく、各リスト項目が文を完成させる場合は、コロンを省略し、項目によって文を完成させるようにしてください。 導入部分を完全な節に強制すると、 コロン規則 を満たすためにフィラー ("the following", "these prerequisites") が追加されるだけの場合、これが正しい選択です。
ArgoCDドメインを構成する前に、
- デプロイされたCNE環境
- 登録済みドメイン（例：
argocd.mydomain.com）
各項目は導入部分（「CNE環境が展開されている必要があります」）を完成させるため、コロンや間投詞は必要ありません。
番号付きリスト形式
すべての項目に 1. の番号を付けます。 （自動採番） 行間はシングルスペースでもダブルスペースでも構いません。各項目が複数の段落を含む場合、または複数行にわたる場合は、項目間に空白行を入れてください。
1. これは番号付きリストです。 この段落が終わったら、2番目の段落を1番目の段落の冒頭に揃えてください。
これは最初の項目の2番目の段落です。
1. これは2つ目のアイテムです。
1. これは3つ目のアイテムです。
ステップの紹介
手順の説明に文の断片を使用しないでください。 断片的な文章は、読みにくい宙ぶらりんの構造を残してしまう。 最初のステップに直接進むか、簡潔で完全な文脈を示す文を使用してください。
悪い例（導入部分）：
## フィールドの編集 フィールドを編集するには、 1. ステップ1
良い（直接的な手順）：
## フィールドの編集 1. 「編集」ボタンをクリックしてください。 1. 名前を入力してください...
また、以下の方法もお勧めです（手順の前に簡潔な完全な文章を添える）：
## フィールドの編集 フィールドは、公開されたコンテンツに影響を与えることなくいつでも編集できます。 1. 「編集」ボタンをクリックしてください。 1. 名前を入力してください...
表
| ヘッダー 1 | ヘッダー 2 | ヘッダー 3 |
| :--- | :--- | :--- |
| セル 1 | セル 2 | セル 3 |
| ヘッダー1 | ヘッダー2 | ヘッダー3 |
|---|---|---|
| 細胞1 | 細胞2 | 細胞3 |
比較表
公開ページと非公開ページなど、アイテム間の機能を比較する場合は、チェックマーク付きの表を使用してください。
| 動作 | 公開ページ | 非公開ページ |
| --- | --- | --- |
| 認証されていないユーザーに表示される | ✔ | |
| 閲覧にはログインとサイトメンバーシップが必要 | | ✔ |
| 固有の URL パターン | ✔ | ✔ |
表の説明
説明文は名詞句でも完全な文でも構いませんが、1つの表の中で両方を混在させてはいけません。表内の一貫性が、どちらのスタイルを選ぶかよりも重要です。
- 名詞句の説明文には末尾にピリオドは付けません（リスト項目と同じ慣例です）。
- 完全な文による説明にはピリオドが必要です。
セルに完全な文が必要な場合（例えば、複数の文を含むセルなど）、その列のすべてのセルに完全な文を記入してください。
名詞句の説明：
| 項目 | 説明 |
|---|---|
| 名前 | UIに表示されるオブジェクト名 |
| 範囲 | 応募作品の入手可能性 |
完全な文章による説明：
| 項目 | 説明 |
|---|---|
| 名前 | オブジェクト名はUIに表示されます。 |
| 範囲 | この範囲内のエントリーが利用可能です。 |
見出し
見出しを使って論理的な階層構造を作り、読者が記事をざっと見て、目的の箇所へ移動できるようにしましょう。
- H1: 記事のタイトル。 記事1つにつき、正確に1つ。 文書内の最初の見出し。 記事のタイトルメタデータと一致する必要があります。
- H2: 記事内の主要なセクション。 ほとんどの記事はH2セクションのみで構成されています。
- H3: 主要セクションに、それぞれ独自の見出しが必要な 2 つ以上の異なるサブトピックが含まれている場合のサブセクション。
- H4: 控えめに使用してください。 H3セクション自体に、圧縮できない個別のサブカテゴリが含まれている場合に限ります。
H5とH6は完全に避けてください。 もしそれらに手を伸ばしてしまうようなら、記事の構成を見直す必要があるか、あるいはその内容は別の記事に分けるべきでしょう。
レベルを飛ばさないでください（例えば、H2からH4にジャンプするなど）。 スクリーンリーダーや自動化ツールは、一貫した階層構造に依存している。
変数とプレースホルダー
プレースホルダーを角括弧で囲むことで、コード（通常は山括弧で囲まれる）と区別できます。
デフォルトの HSQL データベースは
[Liferay Home]/dataに保存されます。
画像
ストレージと命名規則
アイコンなど、複数の記事で再利用される画像もあります。 各製品の英語ドキュメントセクションのルートには、共有の 画像 フォルダがあります。
共有イメージの命名規則として、以下の接頭辞のいずれかを使用してください。
アイコン-ボタン-メニュー-
記事ごとの画像は、記事の横にある ./images/ サブディレクトリに格納されます。 それらを連番で命名します: 01.png、 02.pngなど。 スクリーンショットを追加、削除、または並べ替える場合は、番号を振り直して連続性を保ち、記事内で画像が表示される順序と一致するようにしてください。
画像キャプチャ
アイコン画像を20×20ピクセルでキャプチャしてください。 スクリーンショットは、ページに適した幅にリサイズしてください。一般的には、幅800ピクセル以下にしてください。 （HiDPIディスプレイをサポートするには、2倍の解像度でキャプチャし、レンダリング時にレンダリングソフトが対応している場合はダウンスケールしてください。）
代替テキスト
すべての画像には代替テキストが必要です。 代替テキストは単なるラベルではありません。それは、画像の外観だけでなく、その目的を説明する完全な文です。
悪い例: Liferay セットアップウィザード。
良い点： Liferay セットアップウィザードには、データベースの種類と接続を選択するためのフィールドがあります。
説明が必要な複雑な画像（図、ER図、アーキテクチャ図など）については、2段階のアプローチを採用してください。まず、画像を識別するための簡潔な代替テキスト（alt属性）を記述し、次に、記事本文に詳細なテキストによる説明を記述します。
例： コンテンツエントリが下書きから承認されるまでの進行状況を示すワークフロー図。 詳細については、以下のテキストを参照してください。
純粋に装飾的な画像（バナー、情報を追加しないバッジなど）の場合は、空の alt 属性を使用します（alt=""）。 alt属性を完全に省略しないでください。多くのスクリーンリーダーはファイル名を読み上げるようにフォールバックしますが（例： banner-v2.png）、これは邪魔になります。
画像に、周囲の記事には含まれていないテキストが含まれている場合は、alt属性にそのテキストを正確に含めてください。
インラインアイコン
一部のUIコントロールは、テキストラベルではなくアイコンで識別されます。 手順の中で読者を特定のアイコンに誘導する場合、斜体で表記したコントロール名の直後に、括弧で囲んでアイコンをインラインで表示します。
メニューを開くには、 アクション （
）をクリックしてください。
- アイコン を、括弧で囲み、単一のスペースで区切ったラベル の後に配置します。
- 代替テキストはコントロールのUI名です。斜体ラベルと同じテキストです。 これは、上記の代替テキストに関する規則に対する意図的な例外です。 インラインアイコンはラベルの代わりとなる記号なので、説明文ではなく短いラベルが表示されます。 アイコン、 ボタン、または メニュー を追加しないでください (
![Actions]と記述し、![Actions icon]とは記述しないでください)。
アイコンのみのコントロールを複数ステップのナビゲーション パスに連結するには、 ナビゲーション パス を参照してください。
インラインアイコンは、「保存場所と命名規則」で説明されている共有アイコン画像を参照します。../セグメントの数は、ツリー内での記事の階層レベルによって異なります。 アイコンを記事ごとの images/ フォルダにコピーしないでください。
画像キャプション
Markdownはネイティブの画像キャプションをサポートしていません。 代替テキストはキャプションの役割を果たします。表示されている内容とそれがなぜ重要なのかを説明する、完全で分かりやすい文章で記述してください。 代替テキストの内容を周囲の文章に重複して記載しないでください。
スクリーンショット内の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種類の忠告にはそれぞれ特定の目的がある。
- 注: メインコンテンツを補足する背景情報またはコンテキスト。 読者は、その部分を飛ばしても手順に支障はありません。
- ヒント: 読者の体験を向上させるショートカット、ベストプラクティス、または分かりにくいアプローチ。
- 重要: 読者がタスクを正しく完了するために必要な情報。 手順を省略すると、手順が失敗したり、予期しない結果が生じたりする可能性がある場合に使用してください。
- 警告: 無視すると、データ損失、セキュリティ侵害、不可逆的な変更、またはその他の深刻な損害を引き起こす可能性のある情報です。
使用法
!!! ヒント "[ここにタイトルバーにテキストが入ります]"
これはヒントです。 これは[ヒント](https://www.liferay.com 内のリンクです。 警告文ではMarkdown形式の書式設定がサポートされています。