Markdown を使用した技術ドキュメントの書き方

アドビの技術ドキュメント記事は、可読性が高く学習しやすい Markdown という軽量マークアップ言語で記述されます。

アドビのドキュメントコンテンツは GitHub に保存されるので、Markdown の派生バージョンである GitHub Flavored Markdown（GFM）を使用することができます。GFM は、一般的な書式設定のニーズに応える追加の機能を備えています。 さらに、アドビは Markdown に拡張を加えて、メモ、ヒント、埋め込みビデオといったヘルプ関連の機能を使用できるようにしています。

Markdown の基礎

以下の節では、Markdown でのオーサリングの基本について説明します。

見出し

見出しを作成するには、行の先頭でハッシュマーク（#）を使用します。

# This is level 1 (article title)
## This is level 2
### This is level 3
#### This is level 4
##### This is level 5

基本的なテキスト

Markdown では、段落を示す特別な構文はありません。

テキストを​ 太字 ​にするには、2 つのアスタリスクで囲みます。 テキストを​ 斜体 ​にするには、1 つのアスタリスクで囲みます。

   This text is **bold**.
   This text is *italic*.
   This text is both ***bold and italic***.

Markdown の書式設定文字を無視するには、その直前で \ を使用します。

This is not \*italicized\* type.

番号付きリストと箇条書きリスト

箇条書きリストを作成するには、行を 1. または 1) で始めます。ただし、同じリストで混在させないでください。 番号を指定する必要はありません。 GitHub によって自動的に番号が振られます。

1. This is step 1.
1. This is the next step.
1. This is yet another step, the third.

表示：

箇条書きリストを作成するには、行を * または - または + で始めます。ただし、同じリストで混在させないでください。 （同じドキュメント内で * や + などの箇条書き形式を混在させないでください。）

* First item in an unordered list.
* Another item.
* Here we go again.

表示：

リストを埋め込んだり、リスト項目の間にコンテンツを追加することもできます。

1. Set up your table and code blocks.
1. Perform this step.

   ![screen](assets/no-localize/adobe_standard_logo.png)

1. Make sure that your table looks like this:

   | Hello | World |
   |---|---|
   | How | are you? |

1. This is the fourth step.

   >[!NOTE]
   >
   >This is note text.

1. Do another step.

表示：

テーブル

テーブルは Markdown のコア仕様には含まれていませんが、アドビのシステムではテーブル機能を一部サポートしています。 セル内に複数行のリストを記述することはできません。 また、テーブル内に複数行を記述することはお勧めできません。 テーブルを作成するには、パイプ文字（|）を使用して行と列を区切ります。 列のヘッダーを作成するにはハイフンを使用し、各列をパイプ文字で区切ります。 テーブルが正しくレンダリングされるように、テーブルの前には空白行を挿入します。

| Header | Another header | Yet another header |
|--- |--- |--- |
| row 1 | column 2 | column 3 |
| row 2 | row 2 column 2 | row 2 column 3 |

表示：

単純なテーブルならば、Markdown でも十分に記述できます。 しかし、1 つのセルに複数の段落やリストを含むような複雑なテーブルは記述できません。 このようなコンテンツを記述したい場合は、見出しとテキストを使用するなど、別の書式を使用することをお勧めします。

テーブルの作成について詳しくは、以下を参照してください。

リンク

Markdown のインラインリンクの構文は、ハイパーリンクされるテキストを示す [link text] の部分と、それに続くリンク先の URL またはファイル名を示す (file-name.md) の部分から構成されます。

[link text](file-name.md)

[Adobe](https://www.adobe.com)

表示：

Adobe

リポジトリ内の記事へのリンク（相互参照）を作成するには、相対リンクを使用します。 すべての相対リンクオペランドを使用できます。例えば、./（現在のディレクトリ）、…/（後ろの1つのディレクトリ）、…/./（後ろの2つのディレクトリ）などです。

See [Overview example article](../../overview.md)

リンクの構文の詳細については、このガイドのリンクの記事を参照してください。

画像

![Adobe Logo](assets/no-localize/adobe_standard_logo.png "Hover text")

表示：

コードブロック

コードブロックの配置については、文中のインラインコードスタイルと、文と文の間に独立して配置される「囲み」コードブロックの両方がサポートされています。 詳しくは、コードブロックに関する Markdown のネイティブサポートを参照してください。

例：

This is `inline code` within a paragraph of text.

表示：

This is inline code within a paragraph of text.

次に囲みコードブロックの例を示します。

function test() {
 console.log("notice the blank line before this function?");

カスタムの Markdown 拡張

アドビのほとんどの記事では、段落、リンク、リスト、見出しといった標準の Markdown を使用します。 もっとリッチな書式設定をおこなうには、以下のような Markdown 拡張を使用できます。

メモなどの拡張コンポーネントをひとまとめにするには、各行の先頭に Markdown のブロッククォート（>）を使用します。

見出しやコードブロックなどの一般的な Markdown 要素には、拡張プロパティが備わっているものもあります。 デフォルトプロパティを変更する場合は、コンポーネントの後に中かっこ /{ /} で囲んでパラメーターを追加します。 拡張プロパティについては、本文中で説明しています。

メモブロック

特定のコンテンツに注目を集めるために、これらのタイプのメモブロックを使用できます。

メモブロックは文章の流れを妨げることがあるので、多用しすぎないようにします。 メモブロックではコードブロック、画像、リスト、リンクも使用できますが、シンプルで簡潔なメモにするよう心がけてください。

>[!NOTE]
>
>This is a standard NOTE block.

>[!TIP]
>
>This is a standard TIP.

>[!IMPORTANT]
>
>This is an IMPORTANT note.

表示：

ビデオ

埋め込みビデオは Markdown でネイティブにレンダリングされませんが、Markdown 拡張として使用できます。

>[!VIDEO](https://video.tv.adobe.com/v/29770/?quality=12)

表示：

その他の類似項目

AEM の「その他の類似項目」コンポーネントは、記事の末尾に表示されます。 これは関連リンクを示すコンポーネントです。 このコンポーネントは記事のレンダリング時にレベル 2 の見出し（##）と同じ書式で表示されますが、ミニ目次には追加されません。

表示：

UICONTROL と DNL

マークダウンのすべてのヘルプコンテンツは、初めに機械翻訳を使用してローカライズされます。 ローカライズされていないヘルプの場合は、機械翻訳のままとなります。 ただし、過去にローカライズされたヘルプコンテンツの場合、そのコンテンツが人によって翻訳されている間、機械翻訳されたコンテンツがプレースホルダーとして機能します。

``

機械翻訳中、 `` のタグが付けられた項目はローカライゼーションデータベースと照合され、適切な翻訳であるかどうかが確認されます。 UIがローカライズされていない場合、このタグを使用すると、システムは特定の言語（イタリア語のAnalytics参照など）のUI参照を英語で残すことができます。

ソースコンテンツの例：

[!DNL]

原則として、英語のまま残す部分を機械翻訳エンジンに通知する際には「翻訳対象外」リストを使用します。 最も一般的な項目は「Adobe Analytics」、「Adobe Campaign」、「Adobe Target」などの長いソリューション名です。 ただし、その用語が特定の方法や一般的な方法で使用される可能性があるため、英語のまま残すようエンジンに指示する必要がある場合もあります。 この最も明白なケースは、「Analytics」、「Campaign」、「Target」などのソリューションの短い名前です。マシンが、これらは一般的な用語ではなく、ソリューション名であることを理解するのは困難です。 また、このタグは、常に英語で表示するサードパーティの名前や機能、または英語で表示する必要があるフレーズや文といった短い節のテキストにも使用できます。

ソースコンテンツの例：

注意事項とトラブルシューティング

代替テキスト

アンダースコアを含む代替テキストは、正しくレンダリングされません。 例えば、次のような書き方は避けてください。

![Settings_Step_2](/assets/settings_step_2.png)

ベストプラクティスとして、ファイル名にはアンダースコア（_）ではなく、ハイフン（-）を使用するようにします。

![Settings-Step-2](/assets/settings-step-2.png)

アポストロフィと引用符

テキストを Markdown エディターにコピーする場合、そのテキストに「スマート」（カーリー）アポストロフィまたは引用符が含まれていることがあります。 これらの記号はエンコードするか、基本の（ストレートな）アポストロフィまたは引用符に変更する必要があります。 そうしないと、ファイルをパブリッシュしたときに It’s のような文字化けが生じます。

「スマート」バージョンの記号をエンコードするには、以下のようにします。

山かっこ

ファイル内のコードではなく本文テキストで山かっこを使用する場合は（プレースホルダーを表す場合など）、山かっこを手動でエンコードする必要があります。 そうしないと、HTML タグであると解釈されます。

例えば、<script name> を <script name> としてエンコードします。

タイトル内のアンパサンド

タイトル内でアンパサンド（&）を使用することはできません。 代わりに、「および」のように書くか、& というエンコードを使用します。

関連トピック

Markdown のリソース