From 49f0e88305ea467f2bc5c3e3de635f02e880a536 Mon Sep 17 00:00:00 2001 From: Masahiro FUJIMOTO Date: Tue, 17 Aug 2021 23:43:16 +0900 Subject: MDN/Contribute/Markdown_in_MDN を翻訳 (#1950) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 2021/08/07 時点の英語版に同期 --- files/ja/mdn/contribute/markdown_in_mdn/index.html | 417 +++++++++++++++++++++ 1 file changed, 417 insertions(+) create mode 100644 files/ja/mdn/contribute/markdown_in_mdn/index.html (limited to 'files/ja/mdn') diff --git a/files/ja/mdn/contribute/markdown_in_mdn/index.html b/files/ja/mdn/contribute/markdown_in_mdn/index.html new file mode 100644 index 0000000000..21658cef2b --- /dev/null +++ b/files/ja/mdn/contribute/markdown_in_mdn/index.html @@ -0,0 +1,417 @@ +--- +title: MDN の Markdown +slug: MDN/Contribute/Markdown_in_MDN +tags: + - MDN +--- +
{{MDNSidebar}}
+ +
+ +

警告

+ +

現在、 MDN のすべてのコンテンツを HTML から Markdown に変換しているところです。現在、 HTML または Markdown でページを書くことができますが、私たちは一つの章の中で書式を混在させたくありません。

+ +

現時点では、 (訳注: 英語版の) JavaScript のドキュメント (https://developer.mozilla.org/en-US/docs/Web/JavaScript 以下のページ) のみが Markdown になっていますので、このページはサイトのその部分にのみ適用されます。サイトの他の部分については、 HTML でドキュメントを書いてください。

+ +
+ +

このページでは、 Markdown を使用してどのように MDN のドキュメントを書くかを説明します。ベースラインとして GitHub-Flavored Markdown (GFM) を選択し、 GFM では容易にサポートされていない MDN で行う必要のあるいくつかのことに対応するために、いくつかの拡張機能を追加しました。

+ +

ベースライン: GitHub-Flavored Markdown

+ +

MDN Markdown のベースラインは GitHub-Flavored Markdown (GFM、 https://github.github.com/gfm/) です。このページで特に明記されていないものについては、 GFM の仕様を参照してください。また、 GFM は CommonMark (http://spec.commonmark.org/) の上位互換です。

+ +

コードブロックの例

+ +

GFM や CommonMark では、「コードフェンス」を使用して <pre> ブロックを区切ることができます。冒頭のコードフェンスの後には、「情報文字列」と呼ばれるテキストが続くことがあります。仕様書によると、次の通りです。

+ +
+

情報文字列の最初の単語は、通常、コードサンプルの言語を指定するために使用され、コードタグの class 属性に表示されます。

+
+ +

情報文字列には、次のように複数の単語を含めることができます。

+ +
+```fee fi fo fum
+// some example code
+```
+
+ +MDN では、書き手はコードブロックのサンプルにコードフェンスを使用します。ライターは情報文字列の最初の単語を使用してコードサンプルの言語を指定する必要があり、これはブロックの構文強調表示を提供するために使用されます。以下の単語に対応しています。 + + + +例えば、次のようにします。 + +
+```js
+const greeting = "I will get syntax highlighting";
+```
+
+ +

書き手は以下の追加の単語のいずれかを使用することができますが、これらの単語は言語の単語の後に置く必要があります。

+ + + +例: + +
+```js example-good
+const greeting = "I'm a good example";
+```
+
+ +

議論リファレンス

+ +

この課題は https://github.com/mdn/content/issues/3512 で解決しました。

+ +

メモ、警告、コールアウト

+ +

コンテンツの一部に特別な注意を喚起したい場合があります。そのためには、特別な最初の段落を持つ GFM ブロック引用を使用します。 GFM ブロック引用には、「メモ」「警告」「コールアウト」の 3 種類があります。

+ + + +

メモと警告は、出力に Note: または Warning: というテキストが表示されますが、コールアウトは表示されません。このため、コールアウトは、独自のタイトルを提供したい場合に適しています。

+ +

マークアップの処理は、指定された正確な文字ではなく、生成された AST に基づいて行われます。つまり、 <strong>Note:</strong> もメモを生成します。ただし、スタイルの問題として Markdown の構文が必要です。

+ +

複数行は、通常の段落と同じように、空のブロック引用行によって生成されます。さらに、スペースのない複数の行は通常の Markdown の行と同様に扱われ、連結されます。

+ +

ブロック引用には、コードブロックやその他のブロック要素を含めることができます。

+ +

"Note:" や "Warning:" というテキストは、レンダリングされた出力にも表示されるため、翻訳に配慮する必要があります。実際には、 MDN で対応しているすべてのロケールがこれらの文字列の独自の翻訳を提供しなければならず、プラットフォームは構成が特別な処理を必要とすることを示すものとして認識しなければならないことを意味します。

+ +

例

+ +
注
+ +
+> **Note:** これがメモの書き方です。
+>
+> 複数行を入れることもできます。
+
+ +

これで次のような HTML が生成されます。

+ +
+<div class="notecard note">
+  <p><strong>Note:</strong> これがメモの書き方です。</p>
+  <p>複数行を入れることもできます。</p>
+</div>
+
+ +

この HTML は次のように、強調ボックスとして描画されます。

+ +
+

Note: これがメモの書き方です。

+

複数行を入れることもできます。

+
+ +
警告
+ +
+> **Warning:** これが警告の書き方です。
+>
+> 複数の段落を入れることもできます。
+
+ +

これで次のような HTML が生成されます。

+ +
+<div class="notecard warning">
+  <p><strong>Warning:</strong> これが警告の書き方です。</p>
+  <p>複数の段落を入れることもできます。</p>
+</div>
+
+ +

この HTML は次のように、強調ボックスとして描画されます。

+ +
+

Warning: これが警告の書き方です。

+

複数の段落を入れることもできます。

+
+ +
コールアウト
+ +
+> **Callout:** **これがコールアウトの書き方です。**
+>
+> 複数の段落を入れることもできます。
+
+ +

これで次のような HTML が生成されます。

+ +
+<div class="callout">
+  <p><strong>これがコールアウトの書き方です。</strong></p>
+  <p>複数の段落を入れることもできます。</p>
+</div>
+
+ +

この HTML は次のように、強調ボックスとして描画されます。

+ +
+

これがコールアウトの書き方です。

+

複数の段落を入れることもできます。

+
+ +
翻訳された警告
+ +

(訳注: 現時点では日本語の見出しには対応していません。)

+ +

例えば、ドイツ語で "Warning" を "Warnung" としたい場合、ドイツ語のページで次のように書きます。

+ +
+> Warnung: So schreibt man eine Warnung.
+
+ +

これは次のように表示されます。

+ +
+<div class="notecard warning">
+  <p><strong>Warnung:</strong> So schreibt man eine Warnung.</p>
+</div>
+
+ +
コードブロックを含むメモ
+ +

この例はコードブロックを含んでいます。

+ +
+> **Note:** これがメモの書き方です。
+>
+> コードブロックを含むことができます。
+>
+> ```js
+> const s = "コードブロックの中です";
+> ```
+> こんな感じです。
+
+ +

これで次のような HTML が生成されます。

+ +
+<div class="notecard note">
+  <p><strong>Note:</strong> これがメモの書き方です。</p>
+  <p>コードブロックを含むことができます。</p>
+  <pre class="brush: js">const s = "コードブロックの中です";</pre>
+  <p>こんな感じです。</p>
+</div>
+
+ +

この HTML は次のようにコードブロックと一緒に描画されます。

+ +
+

Note: これがメモの書き方です。

+

コードブロックを含むことができます。.

+ 
const s = "コードブロックの中です";
+

こんな感じです。

+
+ +

議論リファレンス

+ +

この課題は https://github.com/mdn/content/issues/3483 で解決されました。

+ +

定義リスト

+ +

MDN で定義リストを作成するためには、 GFM 順序なしリスト ({{HTMLElement("ul")}}) を変更した書き方をします。

+ + + +

最上位の GFM <li> 要素は、次のように + <dt>/<dd> の組に変換されます。

+ + + +例えば、これは <dl> です。 + +
+* term1
+    * : My description of term1
+
+* `term2`
+    * : My description of term2
+
+      It can have multiple paragraphs, and code blocks too:
+
+      ```js
+      const thing = 1;
+      ```
+
+ +GFM/CommonMark では、これは次の HTML を生成します。 + +
+<ul>
+  <li>
+    <p>term1</p>
+    <ul>
+      <li>: My description of term1</li>
+    </ul>
+  </li>
+  <li>
+    <p><code>term2</code></p>
+    <ul>
+      <li>
+        <p>: My description of term2</p>
+        <p>It can have multiple paragraphs, and code blocks too:</p>
+        <pre>
+          <code class="brush: js">const thing = 1;</code>
+        </pre>
+      </li>
+    </ul>
+  </li>
+</ul>
+
+ +MDN では、これは次の HTML を生成します。 + +
+<dl>
+  <dt>
+    <p>term1</p>
+  </dt>
+  <dd>My description of term1</dd>
+  <dt>
+    <p><code>term2</code></p>
+  </dt>
+  <dd>
+    <p>My description of term2</p>
+    <p>It can have multiple paragraphs, and code blocks too:</p>
+    <pre>
+       <code class="brush: js">const thing = 1;</code>
+    </pre>
+  </dd>
+</dl>
+
+ +

この構文で書かれた定義リストは、 <dt>/<dd> 要素のペアで構成されます。この構文では、 2 つ以上の連続した <dt> 要素、または 2 つ以上の連続した <dd> 要素を持つリストを書くことはできません。パーサーはこれをエラーとして扱います。 MDN 上のほとんどすべての定義リストがこの制限で動作することを期待しており、動作しないものについては、生の HTML に戻ることができます。

+ +

複数の <dt> 項目を 1 つの <dd> に関連付ける必要がある場合の回避策として、以下のように複数の用語をカンマで区切って 1 つの <dt> として提供することを検討してください。

+ +

+* `param1`, `param2`, `param3`
+    * : My description of params 1, 2, and 3
+
+ +

ここで説明する構文の根拠は、 CommonMark を期待するツール (Prettier や GitHub のプレビューなど) で十分に機能すると同時に、記述と解析が適度に簡単であることです。

+ +

議論リファレンス

+ +

この課題は https://github.com/mdn/content/issues/4367 で解決されました。

+ +

表

+ +

GFM では (ただし CommonMark を除く)、表の構文として https://github.github.com/gfm/#tables-extension- があります。これを利用していますが、 GFM の構文は HTML で利用可能な機能の一部しか対応していません。

+ +

ですから、ここでの一般的な原則は、可能な限り GFM Markdown の構文を使用し、必要に応じて生の HTML に戻る必要があるということです。

+ +

GFM の表の構文は、主に以下のような制限があります。

+ + + +

これらのみ対応の機能を使用する必要がある場合は、表を HTML で記述する必要があります。

+ +

また、 <caption> 要素を表に使用することはお勧めしません。これも GFM の構文の規則外になるからです。

+ +

GFM の表の構文では、行の最初と最後のパイプ記号を省略することができます。 MDN の編集者は、読みやすさのためにこれらのパイプ記号を記入する必要があります。

+ +

つまり、 MDN の編集者はこのスタイルを使用する必要があります。

+ +
+| Heading 1 | Heading 2 | Heading 3 |
+|-----------|-----------|-----------|
+| cell 1    | cell 2    | cell 3    |
+| cell 4    | cell 5    | cell 6    |
+
+ +

このスタイルではありません。

+ +
+Heading 1 | Heading 2 | Heading 3
+ --- | --- | ---
+cell 1    | cell 2    | cell 3
+cell 4    | cell 5    | cell 6
+
+ +

議論リファレンス

+ +

この課題は https://github.com/mdn/content/issues/4325 で解決しました。

+ +

上付き・下付き文字

+ +

HTML の {{HTMLElement("sup")}} および {{HTMLElement("sub")}} 要素を必要に応じて使用することができますが、可能な限り代替策を採ってください。具体的には次のようにします。

+ + + +

議論リファレンス

+ +

この課題は https://github.com/mdn/content/issues/4578 で解決しました。

+ +

ページ概要

+ +

ページ概要はページの最初の「コンテンツ」の段落、すなわち、ページのフロントマター、サイドバー、ページバナーのマクロの後に表示される最初のテキストです。

+ +

この概要は検索エンジン最適化 (SEO) のために使用され、また、マクロによってはページリストに自動的に含まれます。 + したがって、最初の段落は、簡潔で説明的なものでなければなりません。

+ +

議論リファレンス

+ +

この課題は https://github.com/mdn/content/issues/3923 で解決しました。

+ +

KumaScript

+ +

文章のコンテンツに、 KumaScript のマクロ呼び出しを含めることができます。

+ +
+
+The **`margin`** [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS) property
+sets the margin area on all four sides of an element. It is a shorthand for
+\{{cssxref("margin-top")}}, \{{cssxref("margin-right")}}, \{{cssxref("margin-bottom")}},
+and \{{cssxref("margin-left")}}.
+
+\{{EmbedInteractiveExample("pages/css/margin.html")}}
+
+The top and bottom margins have no effect on replaced inline elements, such as
+\{{HTMLElement("span")}} or \{{HTMLElement("code")}}.
+
+
-- cgit v1.2.3-54-g00ecf