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

Liferayのスタイル規約

慣習は正しいとか間違っているとかいうものではなく、業界によって大きく異なる判断基準である。 数々の比較検討と使用を経て、Liferayのドキュメントではここに示した表記規則を採用しています。

テキスト編集

自分にとって最も使いやすいテキストエディタを使用してください。 チームのメンバーおよび元メンバーは、以下のエディタを使用しています（アルファベット順）。

  • Atom（またはその派生版）
  • ネオヴィム/ヴィム
  • 崇高なテキスト
  • テキストメイト
  • Visual Studio Code (VS Code)

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

  • 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 Design ドキュメント を参照してください。 注：バッジの構文は、SphinxからLiferayへの移行に伴い、近い将来変更される可能性があります。

番号付きリスト

スペースは1行または2行空け、番号はすべて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 に保存されます。

画像および視覚補助資料

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

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

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

画像品質／撮影

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

画像命名規則

画像ファイル名は連番（01.png、02.pngなど）で付けてください。

画像代替テキスト

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

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をご覧ください。