#AMP by Example
ampbyexample.com gives you a hands-on introduction to Accelerated Mobile Pages based on code and live samples. Learn how to create websites with AMP and how to effectively make use of the different AMP components.
In case we are missing any examples, feel free to let us know. Have you got any good examples you would like to contribute? Read on, it’s very easy to add new examples.
- Fork the repository.
- Install NodeJS. You will need version 4.0.0 or above.
- Install Gulp via
npm. You may need to usesudodepending on your Node installation.
$ npm install -g gulp
- Set up the repository:
$ git clone https://github.com/YOUR_GITHUB_NAME/amp-by-example.git
$ cd amp-by-example
$ npm install
- Build and run the site:
$ gulp
- If everything went well,
gulpshould now be running the site on http://localhost:8000/
Create a new example with gulp create. Set the title via --name or -n and add it to an existing section using --dest or -d:
$ gulp create --name amp-img --dest src/20_Components
$ vim src/20_Components/amp-img.html
For more descriptive example names including whitespaces use quotes:
$ gulp create --name 'Hello World' --dest src/10_Introduction
$ vim src/10_Introduction/Hello_World.html
If you want to create a new sample category, use --category or -c. Prefix the name with two digits followed by a space to define the sort order:
$ gulp create --name amp-awesome --category "50 More Awesomeness"
$ vim src/50_More_Awesomeness/amp-awesome.html
Run validate to validate all examples against AMP spec:
$ gulp validate
Run build to generate all examples:
$ gulp build
While working on an example you can start a local webserver with auto-reload on http://localhost:8000/ by running gulp:
$ gulp
Some components, like this one require an additional server endpoint.
Use HTML comments (<!-- ... -->) to document your sample code:
<!-- Look! Images in AMP. -->
<amp-img src="img/image1.jpg" width=200 height=100 layout=responsive></amp-img>This works for elements in the header as well:
<head>
<!-- Import the amp-youtube component -->
<script async custom-element="amp-youtube" src="https://cdn.ampproject.org/v0/amp-youtube-0.1.js"></script>
...
</head>Every HTML comment creates a separate example section spanning the following HTML element.
<!-- This comment spans the whole following div including the two images -->
<div>
<amp-img src="img/image1.jpg" width=200 height=100 layout=responsive></amp-img>
<amp-img src="img/image2.jpg" width=200 height=100 layout=responsive></amp-img>
</div>Nested comments are not supported:
<!-- A comment -->
<div>
<!-- This does not work -->
<amp-img src="img/image1.jpg" width=200 height=100 layout=responsive></amp-img>
</div>You can use markdown to format your documentation:
<!--
A simple [responsive](https://www.ampproject.org/docs/guides/responsive/control_layout.html)
image - *width* and *height* are used to determine the aspect ratio.
-->
<amp-img src="img/image1.jpg" width=200 height=100 layout=responsive></amp-img>You can mark samples as drafts if they are still work-in-progress. This means the samples won't show up in the start page.
<!---{
"draft": true
}--->If your sample is using one or more experimental features, you can add a metadata section (<!--- ... --->) with the JSON variable experiments to specify which experiments to enable. This will skip its validation and add an experimental note with instructions to your sample:
<!---{
"experiments": ["amp-experiment-name", "amp-experiment-another-name"]
}--->Visually rich examples can provide a preview mode like this. Enable via metadata in the sample:
<!---{
"preview": "default"
}--->It is possible to make the preview mode the default version via:
<!---{
"preview": "default",
"default": "preview"
}--->There is a special preview mode for AMP for Ads (A4A) samples:
<!---{
"preview": "a4a"
}--->If your sample looks better with a single column layout, you can disable the code and preview columns adding the following flags to your sample file:
<!---{
"hideCode": true,
"hidePreview": true
}--->If you need to run or write a sample that depends on the backend server, you can run a local version.
-
Install the Google App Engine SDK for Go and follow the instructions for adding
goappto yourPATH. -
Run the backend server in watch mode so it will recompile on change.
$ gulp backend:watch -
If everything went well, the full site should now be running on http://localhost:8080/
Sample specific backend endpoints should be defined in their own file, e.g. for a sample amp-my-component.html the backend should be backends/amp-my-component.go.
You can’t reference external stylesheets when creating samples. AMP by Example provides a default styling for common elements (p, h1, h2, h3, a, ...) which you should use. Sample specific styles must live in the head of the document using the tag <style amp-custom>. Try to keep the additional CSS for samples to a minimum and use the default styles as often as possible. If you compile a sample via Gulp and run it, the default styling will be applied.
Please note: if you copy code from a sample's code section, you will not get the style that you can see in the preview section.
Please see the CONTRIBUTING file for information on contributing to amp-by-example.
AMP by Example is made by the AMP Project, and is licensed under the Apache License, Version 2.0.