Table of contents

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.

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]

Links

Guides and tutorials are filterable by AMP format, such as AMP websites or AMP stories. Readers who filter their content often want to keep it this way. When linking out to a different guide or tutorial, use the following structure:

 [link]({{g.doc('/content/amp-dev/documentation/guides-and-tutorials/learn/amp-actions-and-events.md', locale=doc.locale).url.path}}?format=websites)

The structure can be broken down into:

//Explains it is a page that exists in the docs repository.

({{g.doc

// When linking to another guide and tutorial this will be the filepath, 
// fill in the rest with the proper document route. 

/content/amp-dev/documentation/guides-and-tutorials

//If linking to an example.

/content/amp-dev/documentation/examples/

//Keeps the document on the chosen language, if available. 

locale=doc.locale

//Explains the page exists in the docs repository.

)url.path}}


//Define the filtered format. 
//Default to websites if your document is relevant to websites and another format. 

?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