Liferayスタイルの規約

慣習は正しいとか間違っているとかいうものではなく、業界内で大きく異なる決定事項です。 多くの比較と使用を経て、Liferay のドキュメントではここに示す規則が使用されています。

テキスト編集

自分に最適なテキスト エディターを使用してください。 チームのさまざまなメンバーと元メンバーが次のエディターを使用しています (アルファベット順)。

• Atom（またはそのフォーク）
• ネオビム/ヴィム
• 崇高なテキスト
• テキストメイト
• ビジュアルスタジオコード（VSコード）

エディターが次の機能を実行できることを確認してください。

• Markdown だけでなく、Liferay で使用されるさまざまなプログラミング言語 (Java、JavaScript、FreeMarker、Groovy/Gradle、XML、JSON など) の構文も強調表示されます。
• 自動スペルチェック。 単語がスペルチェッカーによって自動的に強調表示されると、エラーを見つけられる可能性が高くなります。
• 動的な単語の折り返し。 表をフォーマットするにはこれをオフにし、段落に戻るにはオンに戻す必要があります。

初めてで、どのエディターを使用すればよいか分からない場合は、誰にでも聞いてください。チーム全体が、それぞれのエディターを熱心に推奨しています。

スペース/タブ

タブではなくスペースを使用してください。 これは Liferay コード標準とは逆ですが、Markdown でのインデントはタブよりもスペースを使用する方がはるかに効果的です。

記事の命名

記事名 (ファイル名) は記事のタイトルと同じで、すべて小文字で、スペースをダッシュに置き換えます。 たとえば、「メッセージボードの使用」というタイトルの記事がある場合、記事のファイル名は using-message-boards.mdになります。 序論に「 [主題] の紹介」というタイトルを付けないでください。

改行

段落は 1 行のテキストです。動的なワードラップを使用し、80 列で改行しないでください。 2 つの改行を使用して段落を区切ります。

例:

これは段落です。

これは別の段落です。

テキストの書式設定

**Bold**

*Italics*

\`\`\`Code\`\`\`

太字

太字が多すぎると気が散ってしまうため、ドキュメントでは太字を控えめに使用します。 読者の目は、他の何よりも太字のテキストに引き付けられます。 すべての見出しは太字なので、本文自体では太字を避けます。 太字はフィールド定義の 1 か所で使用されます。

ユーザーが入力できるフォームを説明するときは、フィールド名に太字を使用します。

例:

名前: ユーザーの名前を入力します。

住所: ユーザーの住所を入力します。

フォーム要素のリストでセクションを終了しないでください。

イタリック体

斜体は太字よりも多くの場所で使用されます。 以下に斜体を使用する場合のガイドラインを示します。

概念の紹介

概念を紹介する場合は、初めて使用するときにその概念を斜体にします。 それ以降の概念を斜体にしないでください。

例: Liferay Portal/DXP は多くの OSGi モジュールで構成されています。 モジュールは、自己完結型のアプリケーション、または既存の機能の拡張となる機能の一部です。

モジュール は、初めて使用されるときには斜体で表示されますが、最初の導入後に使用されるときには斜体で表示されないことに注意してください。

UI要素

UI 内の何かをクリックするようにユーザーに指示する場合は、それを斜体にします。

例: 続行するには、 [保存] をクリックします。

UI 要素を参照しているが、ユーザーへの指示がない場合は大文字にしますが、 斜体にしないでください 。

例: ボタンをクリックすると、構成ページが表示されます。

UI 要素をできるだけ明確にするには、上記の 2 つのルールを組み合わせます。

例: [構成] ページで、 [追加] ボタンをクリックします。

ユーザーへの指示が含まれる UI 要素は斜体で表示されますが、指示がない UI 要素は斜体で表示されません。

コード

3 つのチェックマーク (```) とコード構文の識別子を使用して、コード ブロックをオフセットします。 たとえば、Java コードのブロックがある場合は、次のようにオフセットします。

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

次の項目を 1 つのチェック マークで囲むと、コードとして文中に表示されます。

• ファイル名
• クラス
• データベーステーブル
• 変数
• フォルダ/ディレクトリ

UI要素を参照する

UI 要素に言及するときは、大文字で表記します。

例: [ユーザーの編集] 画面で、 [アドレス ] フィールドにアドレスを入力します。

例: ユーザーを追加する 組織 を選択します。

バッジ

現在、サブスクリプション、サポート対象外、バージョンの 3 つのバッジがあります。 バッジを使用して、記事またはセクションを適切にマークします。

サブスクリプション: サブスクリプション バッジを使用して、オープンソース 製品には表示されず、商用製品にのみ表示される機能をマークします。

<span class="bdg bdg-primary">Subscription</span>

サポートされていません: サポートされていないバッジを使用して、存在するがサポートされていない機能をマークします。

<span class="bdg bdg-warning">Unsupported</span>

バージョン: バージョン バッジを使用して、製品の特定のバージョンに表示される機能をマークします。

<span class="bdg bdg-secondary">7.4 U15+ and GA15+</span>

詳細については、バッジに関する Sphinx 設計ドキュメント を参照してください。 注意: バッジの構文は、Sphinx から Liferay への移行に伴い、近い将来変更される可能性があります。

番号付きリスト

シングル/ダブルスペース、すべてに 1 を番号付けします。 複数の段落は、最初の段落が始まる位置までインデントする必要があります。

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

   This would be the second paragraph in the first item.

1. This is the second item in a numbered list.

1. This is the third item in a numbered list.

テーブル

| header 1 | header 2 | header 3 |
| :--- | :--- | :--- |
| cell 1 | cell 2 | cell 3 |

ヘッダー1	ヘッダー2	ヘッダー3
セル1	セル2	セル3

定義

定義は段落であり、定義される項目はコロンとともに太字で表示されます。 決して箇条書きにしてはいけません。 以下に 2 つの定義例を示します。

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

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

定義では、定義する用語を定義内で使用してはなりません。

変数/プレースホルダー

プレースホルダーを必要とする構成例がある場合は、プレースホルダーを角括弧で囲みます。 これは、プレースホルダーをコード、特に大なり記号と小なり記号で囲まれることが多いマークアップ コードと区別するためです。

例:

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

画像と視覚教材

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

命名規則として、次のいずれかのプレフィックスを使用します。

• アイコン-
• ボタン-
• メニュー-

画質 / キャプチャ

20x20 の解像度でアイコン画像をキャプチャします。 スクリーンショットのサイズをページに適した幅（幅 800 ピクセル以下）に変更します。

画像の命名

画像に連番（01.png、02.png）などの名前を付けます。

画像の代替テキスト

すべての画像には代替テキストが必要であり、少なくとも 1 つの説明的な完全な文が必要です。 つまり、単純なラベルで構成された代替テキストだけでは不十分です。 altテキストにはこれを行わないでください:

Liferay セットアップ ウィザード。

代わりに、次のようにします。

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

視覚障害者はスクリーン リーダーを使用してドキュメントを読むため、画像で説明している内容を適切に説明する必要があります。

訓戒

読者の注意を引くために警告を使用します。 警告は、重要な点を強調するために本文から目立たせます。

訓戒を過度に使用しないでください。 警告が頻繁に発生すると、読者はそれを読み飛ばしてしまいます。

最も頻繁に使用される警告は、 ヒント、 警告、 注意、および 重要です。

使用量

!!! 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を参照してください。