A hands-on introduction to Accelerated Mobile Pages (AMP) focusing on code and live samples.
HTML JavaScript Go CSS Shell
Clone or download
nainar and sebastianbenz Add <amp-orientation-observer> demo (#1448)
* Add amp-orientation-observer demo

* Comment + linters

* Add headers and standalone preview mode.

* Validate
Latest commit 31a1548 Aug 14, 2018
Permalink
Failed to load latest commit information.
.github/ISSUE_TEMPLATE Update issue templates Jun 18, 2018
.well-known Add gulp task for assetlinks Aug 26, 2016
api External consent dialog iframe example (#1336) Jul 24, 2018
backend Serve static files with normal CORS headers (#1438) Aug 8, 2018
data add amp-ad section (#801) May 11, 2017
lib Make sidebar sample valid (#1432) Aug 3, 2018
playground fix playground manifest URL (#1426) Aug 1, 2018
scripts add license to missing license files Jul 12, 2016
spec Make sidebar sample valid (#1432) Aug 3, 2018
src Add <amp-orientation-observer> demo (#1448) Aug 14, 2018
static Copy button example (#1399) Jul 30, 2018
tasks Fix stories bookend configuration. (#1435) Aug 3, 2018
templates Add logic for creating hidable "hints" in sample code (#1338) Jul 31, 2018
.amp-by-example.json.enc add travis config Feb 24, 2016
.bowerrc add bower for frontend packages Jul 1, 2016
.eslintrc Cleanup gulpfile (#1372) Jul 26, 2018
.gitignore Add .vscode to gitignore (#1424) Jul 31, 2018
.npmignore Add embed compiler (#769) Apr 28, 2017
.travis.yml run clean in sequence when validating Feb 11, 2017
AUTHORS Initial Commit Feb 16, 2016
CONTRIBUTING.md Fix markdown errors in contributing.md (#1120) Jan 14, 2018
LICENSE Fix broken find/replace across project (#1329) Jun 26, 2018
README.md Add logic for creating hidable "hints" in sample code (#1338) Jul 31, 2018
app.yaml add sample checkout flow (#1010) Nov 15, 2017
bower.json add serviceworker for caching Jul 1, 2016
client-secret.json.enc remove not needed api key Feb 25, 2016
default.profraw use toggle Aug 2, 2018
deploy.sh Update go_appengine version Jul 16, 2018
gulpfile.js Make sidebar sample valid (#1432) Aug 3, 2018
index.html Add Polymer shell (#930) Sep 22, 2017
package-lock.json Update dependency gulp-eslint to v5 (#1400) Jul 27, 2018
package.json Update dependency gulp-eslint to v5 (#1400) Jul 27, 2018
renovate.json Add renovate.json (#1361) Jul 26, 2018
server.go Add server-side for amphtml-email, fix validation error with friend r… Jul 30, 2018

README.md

Build Status

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.

Installation

  1. Fork the repository.
  2. Install NodeJS. You will need version 4.0.0 or above.
  3. Install Gulp via npm. You may need to use sudo depending on your Node installation.
$ npm install -g gulp
  1. Set up the repository:
$ git clone https://github.com/YOUR_GITHUB_NAME/amp-by-example.git
$ cd amp-by-example
$ npm install
  1. Build and run the site:
$ gulp
  1. If everything went well, gulp should now be running the site on http://localhost:8000/

Creating a new sample

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.

Writing the sample

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 section including the two images -->
<section>
  <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>
</section>

Nesting comments are not supported:

<!-- A comment -->
<div>
  <!-- This does not work because the parent div has already a comment -->
  <amp-img src="img/image1.jpg" width="200" height="100" layout="responsive"></amp-img>
</div>
<div>
  <!-- Commenting inside nested tags works though -->
  <amp-img src="img/image1.jpg" width="200" height="100" layout="responsive"></amp-img>
</div>

If your comment spans multiple elements, wrap these in an single div without any attributes. The enclosing div tag will be hidden in source code listings:

<!-- The enclosing `div` will be hidden in source code listings. -->
<div>
  <button on="tap:my-lightbox" role="button" tabindex="0">Open lightbox</button>
  <amp-lightbox id="my-lightbox" layout="nodisplay">
    <h1>Hello World!</h1>
  </amp-lightbox>
</div>

Formatting

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>

Hints

If you'd like to add additional information about a single element inside a section, use the <!--~ hint syntax ~-->:

<!-- A comment about the form. -->
<form method="post"
  action-xhr="https://example.com/subscribe"
  target="_top">
  <fieldset>
    <input type="text" name="username">

    <!--~ Addition explanation about the hidden field. ~-->
    <input type="hidden" name="id" value="abc">
  </fieldset>
</form>

This will make the <input> element clickable, with the additional explanation appearing on click.

Drafts

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

Experimental Features

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"]
}--->

Preview Mode

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 Ad samples:

<!---{
  "preview": "a4a"
}--->

Single Column Layout

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

Disabling the Playground

If it doesn't make sense for your sample to provide a playground link, you can disable it:

<!---{
  "disablePlayground": true
}--->

Running the backend server

If you need to run or write a sample that depends on the backend server, you can run a local version.

  1. Install the Google App Engine SDK for Go.

  2. Run the backend server in watch mode so it will recompile on change.

    $ gulp backend:watch
    

    If you get an error message can't find import: "golang.org/x/net/context", you have to manually install and configure the GO appengine environment:

    # install the google.goland.org/appengine package
    $ go get google.golang.org/appengine
    # explicitly set the GOROOT and APPENGINE_DEV_APPSERVER env vars
    $ export GOROOT=$HOME/local/google-cloud-sdk/platform/google_appengine/goroot
    $ export APPENGINE_DEV_APPSERVER=$(which dev_appserver.py)
    
  3. If everything went well, the full site should now be running on http://localhost:8080/

Adding backend functionality

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.

How to style examples

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.

Contributing

Please see the CONTRIBUTING file for information on contributing to amp-by-example.

License

AMP by Example is made by the AMP Project, and is licensed under the Apache License, Version 2.0.