書式設定ガイドとチュートリアル

ガイドとチュートリアルは、追加の Frontmatter とショートコードの書式設定とともに Markdown に提出します。

ドキュメントの場所

amp.dev のコンテンツは、amp.dev と AMPHTML の 2 つのレポジトリから pull されます。components の下のすべてのリファレンスドキュメントは、AMPHTML の builtins または extensions から pull されます。

ほかにも、AMPHTML から amp.dev にインポートされるドキュメントがいくつかあります。これらは、このファイルにリストされています。これらの amp.dev 内のドキュメントを更新しないでください。変更内容は、以降のビルドで上書きされます！

Frontmatter

Frontmatter は、各ガイドとチュートリアルの最上位にあります。

次に例を示します。

$title: Include Custom JavaScript in AMP Pages
$order: 7
formats:
  - websites
author: CrystalOnScript
contributors:
  - fstanis
description: For web experiences requiring a high amount of customization AMP has created amp-script, a component that allows the use of arbitrary JavaScript on your AMP page without affecting the page's overall performance.

`$title`	目次に表示されるドキュメントの題名です。“AMP” やその他の固有名詞以外は、最初の単語の先頭の英字を大文字にします。単語の `and` の代わりにアンパサンド記号の `&` を使用してください。
`$order`	目次のどこにドキュメントが表示されるかを定義します。正しい位置に表示されるように、ほかのドキュメントで `$order` を編集する必要がある場合があります。
`formats`	ドキュメントに関連する AMP エクスペリエンスをリストします。ドキュメントが AMP ウェブサイトと AMP ストーリーに関連しており、AMP 広告や AMP メールに関連していない場合は、Frontmatter を ```yaml formats: - websites - stories ``` のようにします。
`author`	作成者はあなたです！あなたの GitHub ユーザー名を使用してください。
`contributors`	ドキュメントに貢献した人をリストします。このフィールドはオプションです。
`description`	ガイドまたはチュートリアルに関する簡単な説明文を記述します。この内容をもとに検索エンジンが最適化され、ドキュメントを必要とする人に届けられます！
`tutorial`	ウェブサイトの Frontmatter に `tutorial: true` を追加すると、チュートリアルアイコンがウェブサイトの隣に追加されます。チュートリアルのセクションは目次の下部にあります。

ショートコード

ショートコードとその使用方法のリストについては、GitHub の documentation.md を参照してください。

画像

amp.dev は AMP で作られています！そのため、画像は amp-img 基準に一致していなければなりません。ビルドプロセスでは、以下の構文により、画像を適切な amp-img 形式に変換しています。

セクションのフィルタリング

ドキュメントには、複数の AMP 形式に関連性のあるものもあれば、ほかの形式には関連性のない説明や情報がさらに必要なものもあります。こういったセクションについては、以下のショートコードで囲むことでフィルタリングすることができます。

&lsqb;filter formats="websites"]
This is only visible for [websites](?format=websites).
&lsqb;/filter]

&lsqb;filter formats="websites"]
This is only visible for [websites](?format=websites).
&lsqb;/filter]

&lsqb;filter formats="websites, email"]
This is visible for [websites](?format=websites) & [email](?format=email).
&lsqb;/filter]

&lsqb;filter formats="stories"]
This is visible for [stories](?format=stories).
&lsqb;/filter]

ヒント

以下のショートコードでテキストを囲むことで、ヒントとコールアウトを追加できます。

&lsqb;tip type="default"]
Default tip
[/tip]

&lsqb;tip type="important"]
Important
[/tip]

&lsqb;tip type="note"]
Note
[/tip]

&lsqb;tip type="read-on"]
Read-on
[/tip]

コードスニペット

コードスニペットは、3 連バックティックの間に配置し、言語を最初の 3 連バックティックセットの最後に指定します。

```html
  // code sample

```css
// code sample

  // code sample
```</pre></div>

コードに二重波かっこが含まれる場合、コードの部分が囲まれている必要があります。二重波かっこは、[`amp-mustache`](../../../../documentation/components/reference/amp-mustache.md?format=websites) テンプレートを使用している場合に見られることがよくあります。

<div class="ap-m-code-snippet"><pre>```html<br><br>  // code with double curly braces<br><br>```</pre></div>

### リスト内のコードスニペット

Python-Markdown にはいくつかの制限があります。リストにコードスニペットを含める場合は、次の構文を使用してください。

<div class="ap-m-code-snippet"><pre>&lsqb;sourcecode:html]
      <html>
        <p>Indented content.</p>
      </html>
    &lsqb;/sourcecode]</pre></div>

## コードサンプルのプレビュー

コードサンプルにはプレビューや [AMP Playground](https://playground.amp.dev/) バージョンへのリンクを使用できます。

<div class="ap-m-code-snippet">
  <pre>&lsqb;example preview="default: none|inline|top-frame"
          playground="default: true|false"
          imports="<custom-element-1>,<custom-element-2>,..."
          template="<custom-template>"]
  ```html
    // code sample

[/example]

プレビューは、Playground で開くと、現在選択されている形式に自動的に変換されます 🤯！

プレビューがどのように生成されるかを定義するには、preview 属性を使用します。

none: プレビューは生成されません
inline: プレビューの例はソースコードの上に表示されます。インラインプレビューは、コードに head 要素が含まれていない場合に、通常のウェブサイトの例でのみ使用できます。このオプションは、スタイル付けやほかの head 要素が不要である小さな例に使用します（インポートは imports 属性で指定されるため、この制限に考慮されません）。
top-frame: プレビューの例は、iframe 内のソースコードの上に表示されます。portrait と landscape モードで向きを切り替えることができます。次のように属性を追加指定することで、向きをあらかじめ選択することができます。
orientation: default: landscape|portrait

カスタム要素が必要な場合は、コンポーネント名の後にコロンとバージョンを付けて、カンマ区切りのリストとして imports 属性に指定します。コードに amp-mustache が使用されている場合は、代わりに template 属性に依存関係を指定してください。

リソースリンク付きのメールコンテンツについては、ソースにプレースホルダのを使用します。

インラインサンプル

以下は、単純な埋め込みのインラインサンプルです。インラインスタイルで CSS を定義できます。



  
     Hello World
  
    ```html
    Hello World
    ```
  [/example]

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

[example preview="inline" playground="true"]

<div style="background: red; width: 200px; height: 200px;">Hello World</div>

このスニペットを Playground で開く

警告: インラインサンプルは、ページに直接埋め込まれるため、ページ上ですでにコンポーネントが使用されている場合（amp-consent など）に競合が発生する可能性があります。

トップフレームプレビュー

ヘッダー要素を指定したり、グローバルスタイルを <style amp-custom> 内に定義したりする必要がある場合は、トップフレームプレビューを使用します。

ヘッダーに AMP ボイラープレートコードを追加しないでください。AMP ボイラープレートは AMP 形式に基づいて自動的に追加されます。サンプルで必要とされる要素のみをヘッダーに追加してください！

  [example preview="top-frame"
         playground="true"]
    ```html
    <head>
      <script async custom-element="amp-youtube" src="https://cdn.ampproject.org/v0/amp-youtube-0.1.js"></script>
      <style amp-custom>
        body {
          background: red;
        }
      </style>
    </head>
    <body>
      <h1>Hello AMP</h1>
      <amp-youtube width="480"
        height="270"
        layout="responsive"
        data-videoid="lBTCB7yLs8Y">
      </amp-youtube>
    </body>
    ```
  [/example]

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

<head>
  <script
    async
    custom-element="amp-youtube"
    src="https://cdn.ampproject.org/v0/amp-youtube-0.1.js"
  ></script>
  <style amp-custom>
    body {
      background: red;
    }
  </style>
</head>
<body>
  <h1>Hello AMP</h1>
  <amp-youtube
    width="480"
    height="270"
    layout="responsive"
    data-videoid="lBTCB7yLs8Y"
  >
  </amp-youtube>
</body>

このスニペットを Playground で開く

AMP ストーリー

AMP ストーリーのプレビューには、preview="top-frame" と orientation="portrait" を合わせて使用します。

  [example preview="top-frame"
         orientation="portrait"
         playground="true"]
    ```html
    <head>
      <script async custom-element="amp-story"
          src="https://cdn.ampproject.org/v0/amp-story-1.0.js"></script>
      <style amp-custom>
        body {
          font-family: 'Roboto', sans-serif;
        }
        amp-story-page {
          background: white;
        }
      </style>
    </head>
    <body>
      <amp-story standalone>
        <amp-story-page id="cover">
          <amp-story-grid-layer template="vertical">
            <h1>Hello World</h1>
            <p>This is the cover page of this story.</p>
          </amp-story-grid-layer>
        </amp-story-page>
        <amp-story-page id="page-1">
          <amp-story-grid-layer template="vertical">
            <h1>First Page</h1>
            <p>This is the first page of this story.</p>
          </amp-story-grid-layer>
        </amp-story-page>
      </amp-story>
    </body>
    ```
  [/example]

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

<head>
  <script
    async
    custom-element="amp-story"
    src="https://cdn.ampproject.org/v0/amp-story-1.0.js"
  ></script>
  <style amp-custom>
    body {
      font-family: 'Roboto', sans-serif;
    }
    amp-story-page {
      background: white;
    }
  </style>
</head>
<body>
  <amp-story standalone>
    <amp-story-page id="cover">
      <amp-story-grid-layer template="vertical">
        <h1>Hello World</h1>
        <p>This is the cover page of this story.</p>
      </amp-story-grid-layer>
    </amp-story-page>
    <amp-story-page id="page-1">
      <amp-story-grid-layer template="vertical">
        <h1>First Page</h1>
        <p>This is the first page of this story.</p>
      </amp-story-grid-layer>
    </amp-story-page>
  </amp-story>
</body>

このスニペットを Playground で開く

AMP メールの絶対 URL

AMP メールにを埋め込む場合に、それをどのように使用してエンドポイント URL を絶対 URL にしているか、注意してください。

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

[example preview="top-frame" playground="true"]

<div class="resp-img">
  <amp-img
    alt="flowers"
    src="/static/inline-examples/images/flowers.jpg"
    layout="responsive"
    width="640"
    height="427"
  ></amp-img>
</div>

このスニペットを Playground で開く

mustache テンプレートのエスケープ処理

以下は、リモートエンドポイントを使用した top-frame サンプルです。Mustache テンプレートは、とを使用して、サンプルでエスケープ処理する必要があります。

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

[example preview="top-frame" playground="true" imports="amp-list:0.1" template="amp-mustache:0.2"]

<amp-list
  width="auto"
  height="100"
  layout="fixed-height"
  src="/static/inline-examples/data/amp-list-urls.json"
>
  <template type="amp-mustache"
    >
    <div class="url-entry">
      <a href="{{url}}">{{title}}</a>
    </div>
  </template>
</amp-list>

このスニペットを Playground で開く

リンク

標準的なマークダウンのリンク構文を使って、ほかのページにリンクすることができます。

[link](../../../courses/beginning-course/index.md)

amp.dev の別のページにリンクする場合、参照はそのターゲットファイルへの相対ファイルパスになります。

アンカー

ドキュメント内の特定のセクションへのリンクには、アンカーを使用します。

[link to example section](#example-section)

アンカーがないセクションにリンクする前に、<a name="#anchor-name></a> を使ってアンカーターゲットを作成してください。セクションの見出しの最後に作成するのが適しています。

## Example section <a name="example-section"></a>

アンカーには、文字、数字、ダッシュ、およびアンダースコアのみを使用できます。見出しに一致するか、セクションを説明する短いアンカー名を英語で指定してください。ドキュメント内で一意のアンカー名を指定してください。

ページを翻訳する場合でも、アンカー名は英語のまま、変更してはいけません。

別のページからのリンクに使用されるアンカーを作成する場合は、すべての翻訳で同じアンカーを作成することも必要です。

AMP 形式フィルタ

コンポーネントドキュメント、ガイド、およびチュートリアルと例は、AMP ウェブサイトや AMP ストーリーなどの AMP 形式を使用してフィルタすることができます。そういったページにリンクする場合は、リンクに format パラメータを追加して、ターゲットにサポートされた形式を明示的に指定する必要があります。

[link](../../learn/amp-actions-and-events.md?format=websites)

このパラメータは、ページがサポートするすべての形式をターゲットがサポートするとわかっている場合にのみ省略できます。

コンポーネントリファレンス

コンポーネントリファレンスドキュメントへのリンクは、バージョン部分が省略されている場合、自動的に最新バージョンにポイントされます。あるバージョンに明示的にポイントする場合は、完全名を指定してください。

[latest version](../../../components/reference/amp-carousel.md?format=websites)
[explicit version](../../../components/reference/amp-carousel-v0.2.md?format=websites)

ドキュメント構造

題名、見出し、小見出し

題名、見出し、および小見出しの最初の単語の先頭の英字は大文字にし、後は小文字で続けます。ただし、AMP とほかの固有名詞は例外です。見出しを Introduction としてはいけません。Introduction はドキュメントの題名の後に挿入されます。

ドキュメントの命名

ドキュメントの名前には、ダッシュの命名規則を使用します。

正しい	誤り
hello-world-tutorial.md	hello_world_tutorial.md
website-fundamentals.md	websiteFundamentals.md
actions-and-events.md	actionsandevents.md

Written by @CrystalOnScript