AMP
IT
English Français العربية Español Indonesia 日本語 한국어 Português Русский Türkçe 中文
Something went wrong while trying to load more search results.
We apologize for the inconvenience caused.
Please try again later.

;(

Something went wrong…

…while trying to load the search results.
We apologize for the inconvenience caused.
Please try again later.

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

You can let a code sample have a preview or a link to open the code sample in the 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]

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.

  [example preview="top-frame" orientation="portrait"
          playground="true"
          imports="amp-list:0.1"
          template="amp-mustache:0.2"]
  ```html
  <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>
  ```
  [/example]

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.

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