Need help with amp-by-example?

About the developer

762 Stars 540 Forks Apache License 2.0 1.6K Commits 205 Opened issues


DEPRECATED: AMP by Example has been merged into

Services available


Need anything else?

Contributors list

IMPORTANT: AMP by Example has been merged into All new issues and pull requests should be created here.

AMP by Example


  1. Fork the repository.
  2. Install NodeJS. You will need version 4.0.0 or above.
  3. Install Gulp via
    . You may need to use
    depending on your Node installation.
  $ npm install -g gulp
  1. Set up the repository:
  $ git clone
  $ cd amp-by-example
  $ npm install
  1. Build and run the site:
  $ gulp
  1. If everything went well,
    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
and add it to an existing section using
$ 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

. 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

Some components, like amp-live-list require an additional server endpoint.

Writing the sample

Use HTML comments (

) to document your sample code:

This works for elements in the header as well:


Every HTML comment creates a separate example section spanning the following HTML element.

Nesting comments are not supported:

If your comment spans multiple elements, wrap these in an single

without any attributes. The enclosing
tag will be hidden in source code listings:
Open lightbox

Hello World!

Sample Styling

Sometimes it's good to add a little bit more styling to a sample (e.g. to separate a button from an input field). To make sure that all samples have a consistent styling, please use the following CSS variables to style specific elements in your sample:

:root {
  --color-primary: #005AF0;
  --color-secondary: #00DCC0;
  --color-text-light: #fff;
  --color-text-dark: #000;
  --color-error: #B00020;
  --color-bg-light: #FAFAFC;

--space-1: .5rem; /* 8px / --space-2: 1rem; / 16px / --space-3: 1.5rem; / 24px / --space-4: 2rem; / 32px */

--box-shadow-1: 0 1px 1px 0 rgba(0,0,0,.14), 0 1px 1px -1px rgba(0,0,0,.14), 0 1px 5px 0 rgba(0,0,0,.12); }

You can use them to style your samples like this:

.button {
  margin: var(--space-2);
  padding: var(--space-1);
  background-color: var(--color-primary);
  color: var(--color-text-light);

Only add the ones that you need to the sample. These CSS variable declarations will be added automatically to your sample, if you use

gulp create ...
to create the sample.


screenshot 2018-11-30 at 00 22 57


screenshot 2018-11-30 at 00 23 08


You can use markdown to format your documentation:

Notes, Warnings & Tips

There's a special markup available for callouts:

[tip type="default|important|note|read-on"]

For example:

[tip type="important"]
Warning! This might go wrong.


If you'd like to add additional information about a single element inside a section, use the



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

This will make the

 element clickable, with the additional explanation appearing on click.


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.

Experimental Features

If your sample is using one or more experimental features, you can add a metadata section (

) with the variable 
to specify which experiments to enable. This will skip its validation and add an experimental note with instructions to your sample:

Preview Mode

Visually rich examples can provide a preview mode like this. Enable via metadata in the sample:

There is a special preview mode for AMP Ad samples:

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:

Disabling the Playground

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

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: ""
    , you have to manually install and configure the GO appengine environment:
    # install the package
    $ go get
    # 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
  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

the backend should be

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

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