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 syntax 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]
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
headelements. Use this option for small examples that do not need any styling or otherheadelements (imports do not count, since they are specified via theimportsattribute). -
top-frame: The example preview is displayed above the source code inside an iframe. The orientation can be toggled between
portraitandlandscapemode. 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:
<div style="background: red; width: 200px; height: 200px;">Hello World</div>
amp-consent). Top-Frame Preview
Use top-frame preview whenever you need to specify header elements or define global styles inside <style amp-custom>.
[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>
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>
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>
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>
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 |
-
