AMP
EN
Deutsch Français العربية Español Italiano Indonesia 日本語 한국어 Português Русский Türkçe 中文 Polski Tiếng việt

格式化指南和教程

指南和教程以 Markdown 格式提交，并带有额外的 frontmatter 和短代码格式。

文档位置

amp.dev 上的内容来自两个代码库：amp.dev 和 AMPHTML。组件下的所有参考文档均来自 AMPHTML，无论是以内置形式还是扩展形式。

还有一些其他文档是从 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 Stories 相关，但不与 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 格式。

{{ image('/static/img/docs/tutorials/custom-javascript-tutorial/image1.jpg', 500, 369, layout='intrinsic', alt='Image of basic amp script tutorial starter app') }}

筛选部分

某些文档可能与多种 AMP 格式相关，但某些格式可能需要进一步的解释或信息，而这些信息与其他格式无关。您可以通过将这些部分包装在以下短代码中来筛选这些部分。

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

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

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

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

提示

您可以通过将文本包装在以下短代码中来添加提示和标注

[tip type="default"]
Default tip
[/tip]

[tip type="important"]
Important
[/tip]

[tip type="note"]
Note
[/tip]

[tip type="read-on"]
Read-on
[/tip]

代码片段

将代码片段放在三对反引号内，并在第一对反引号的末尾指定语言。

```html
  // code sample
```

```css
  // code sample
```

```js
  // code sample
```

如果您的代码包含双大括号，如果您使用 amp-mustache 模板，通常会出现这种情况，您必须将代码部分包装起来

```html
{% raw %}
  // code with double curly braces
{% endraw  %}
```

列表中的代码片段

Python-Markdown 有一些限制。在列表中包含代码片段时，请使用以下语法

1. First:
    [sourcecode:html]
      <html>
        <p>Indented content.</p>
      </html>
    [/sourcecode]
  2. Second
  3. Third

预览代码示例

代码示例可以具有预览和/或指向 AMP Playground 版本的链接。

  [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 属性中指定依赖项。

对于包含资源链接的电子邮件内容，请在源中使用占位符 {{server_for_email}}。

内联示例

这是一个简单的内联示例嵌入。您可以通过内联样式定义 CSS

  [example preview="inline" playground="true"]
    ```html
    <div style="background: red; width: 200px; height: 200px;">Hello World</div>
    ```
  [/example]
  [/example]

它看起来是这样的

Hello World
<div style="background: red; width: 200px; height: 200px;">Hello World</div>
在 Playground 中打开此代码段

内联示例直接嵌入到页面中。如果页面上已使用组件（例如 amp-consent），这可能会导致冲突。

顶框预览

当您需要在 <style amp-custom> 中指定标头元素或定义全局样式时，请使用顶框预览。

请勿在标头中添加任何 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 Stories

使用 preview="top-frame" 和 orientation="portrait" 来预览 AMP Stories。

  [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 电子邮件中嵌入，我们将如何使用 {{server_for_email}} 使端点 URL 绝对。

  [example preview="top-frame" playground="true"]
    ```html
    <div class="resp-img">
      <amp-img alt="flowers"
        src="{{server_for_email}}/static/inline-examples/images/flowers.jpg"
        layout="responsive"
        width="640"
        height="427"></amp-img>
    </div>
    ```
  [/example]

它看起来是这样的

 
<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 示例。必须使用 {% raw %} 和 {% endraw %} 转义示例中的 Mustache 模板

[example preview="top-frame"
        playground="true"
        imports="amp-list:0.1"
        template="amp-mustache:0.2"]
    ```html
    <amp-list width="auto" height="100" layout="fixed-height"
      src="{{server_for_email}}/static/inline-examples/data/amp-list-urls.json">
      <template type="amp-mustache">{% raw %}
        <div class="url-entry">
          <a href="{{url}}">{{title}}</a>
        </div>
      {% endraw %}
      </template>
    </amp-list>
    ```
[/example]

它看起来是这样的

 
<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 中打开此代码段

您可以使用标准的 Markdown 链接语法链接到其他页面

 [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 Stories）进行筛选。当链接到此类页面时，您应该明确指定目标支持的格式，方法是将格式参数附加到链接

 [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，引言紧随文档标题之后。

文档命名

使用短划线命名约定命名文档。


正确 错误
hello-world-tutorial.md hello_world_tutorial.md
website-fundamentals.md websiteFundamentals.md
actions-and-events.md actionsandevents.md