Formatting guides & tutorials

Guides and tutorials are submitted in Markdown, with an additional frontmatter and shortcode formatting.

Documentation locations

Content on amp.dev is pulled from two repositories, amp.dev and AMPHTML. All reference documentation under components is pulled from AMPHTML, either from builtins or extensions.

There are several other documents that are imported to amp.dev from AMPHTML. They are listed in this file. Don't update these documents in the amp.dev repository – your changes will get overwritten on subsequent builds!

Frontmatter

Frontmatter exists at the top of each guide and tutorial.

Example:

$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`	The title of your document as it will appear in the table of contents. Capitalize the first letter of the first word, except for “AMP” and other proper nouns. Use the ampersand `&` instead of the word `and`.
`$order`	Define where in the table of contents your document appears. You may need to edit the `$order` in other documents for it to appear in the correct position.
`formats`	List the AMP experiences your document is relevant to. If your document was relevant to AMP websites and AMP stories, but not AMP ads or AMP email, your frontmatter would like the following: `yaml formats: - websites - stories`
`author`	The author is you! Use your GitHub username.
`contributors`	List anyone who contributed to your document. This field is optional.
`description`	Write a brief description of your guide or tutorial. This helps with search engine optimization, getting your work into the hands of those who need it!
`tutorial`	Add `tutorial: true` to the frontmatter for the website to add the tutorial icon next to it. Tutorials are at the bottom of their section in the table of contents.

Shortcodes

For a list of shortcodes and their uses, please view documentation.md on GitHub.

Images

amp.dev is built with AMP! Therefore our images must match the amp-img criteria. The build process uses the following syntact to convert images to proper amp-img format.

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

Filtering sections

Some documents may be relevant for multiple AMP formats, but certain formats may need further explanation or information that is not relevant to the others. You can filter these sections by wrapping them in the following shortcode.

[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]

Tips

You can add tips and callouts by wrapping text in the following shortcode:

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

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

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

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

Code snippets

Place code snippets inside sets of three backticks, specify the language at the end of the first set of backticks.

```html
  // code sample
```

```css
  // code sample
```

```js
  // code sample
```

If your code contains double curly braces, which often is the case if you use amp-mustache templates, you have to wrap the code part:

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

Code snippets in lists

Python-Markdown has some limitations. Use the following syntax when including code snippets in lists:

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

Preview code samples

Code samples can have a preview and/or link to an AMP Playground version.

  [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]

The preview will automatically be transformed to the currently selected format when opening it in the playground 🤯!

Use the preview attribute to define how the preview is generated:

none: No preview will be generated
inline: The example preview is displayed above the source code. An inline preview is only possible for normal website examples if the code does not contain any head elements. Use this option for small examples that do not need any styling or other head elements (imports do not count, since they are specified via the imports attribute).
top-frame: The example preview is displayed above the source code inside an iframe. The orientation can be toggled between portrait and landscape mode. You can preselect the orientation by specifying the additional attribute:
orientation: default: landscape|portrait

If custom elements are needed, specify them in the imports attribute as a comma separated list with the name of the component followed by a colon and the version. If your code uses amp-mustache specify the dependency in the template attribute instead.

For email content with resource links use the placeholder {{server_for_email}} in the source.

Inline Sample

Here is simple inline sample embed. You can define CSS via inline styles:

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

This is what it looks like:

Hello World

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

Open this snippet in playground

inline samples are embedded directly into the page. This might lead to conflicts if components are already used on the page (e.g. amp-consent).

Top-Frame Preview

Use top-frame preview whenever you need to specify header elements or define global styles inside <style amp-custom>.

Do not add any AMP boilerplate code to the header as this will get added automatically, based on the AMP format. Only add elements to the head that are needed by the sample!

  [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]

This is what it looks like:

<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>

Open this snippet in playground

AMP Stories

Use preview="top-frame" together with orientation="portrait" for previewing 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]

This is what it looks like:

  <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>

Open this snippet in playground

Absolute URLs for AMP Email

Note how we use {{server_for_email}} for making the endpoint URL absolute if embedded inside an AMP email.

  [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]

This is what it looks like:

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

Open this snippet in playground

Escaping mustache tempaltes

Here is a top-frame sample using a remote endpoint. Mustache templates need to be escaped in samples using {% raw %} and {% endraw %}:

[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]

This is what it looks like:

<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>

Open this snippet in playground

Links

You can link to other pages with standard markdown link syntax:

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

When linking to another page on amp.dev the reference will be a relative filepath to the target file.

Anchors

Link to specific sections in a document using anchors:

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

Please create the anchor target using <a name="#anchor-name></a> before linking to a section with no anchor present. A good place is at the end of the section headline:

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

You must only use letters, digits, the dash and the underscore in an anchor. Please use short anchor names in english that match the headline or describe the section. Ensure the anchor name is unique inside the document.

When a Page is translated the anchor names must not be changed and remain in english.

When you create an anchor that will be used in a link from another page you should also create the same anchor in all translations.

AMP format filter

Component documentation, guides and tutorials and examples are filterable by AMP format, such as AMP websites or AMP stories. When linking out to such a page you should explicitly specify a format, which is supported by the target, by appending the format parameter to the link:

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

Only when you are sure the target supports all the formats that your page does you can omit the parameter.

Component references

A link to a component reference documentation will automatically point to the latest version if your link omits the version part. When you explicitly want to point to a version specify the full name:

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

Document Structure

Titles, headings and subheadings

The first letter of the first word in titles, headings and subheadings is capitalized, what follows is lowercase. Expectations include AMP and other proper nouns. No heading is titled Introduction, introductions follow the document title.

Document naming

Name documents with the dash naming convention.

Do	Don’t
hello-world-tutorial.md	hello_world_tutorial.md
website-fundamentals.md	websiteFundamentals.md
actions-and-events.md	actionsandevents.md

Written by @CrystalOnScript

Components

{{title}}

Results

{{title}}

;(

Something went wrong…

¯\_(ツ)_/¯

No results found.

Important Components

<{{title}}>

Popular Articles

{{title}}

Formatting guides & tutorials

Documentation locations

Frontmatter

Shortcodes

Images

Filtering sections

Tips

Code snippets

Code snippets in lists

Preview code samples

Inline Sample

Top-Frame Preview

AMP Stories

Absolute URLs for AMP Email

Escaping mustache tempaltes

Links

Anchors

AMP format filter

Component references

Document Structure

Titles, headings and subheadings

Document naming