Skip to content

Latest commit

 

History

History
137 lines (99 loc) · 3.87 KB

README.md

File metadata and controls

137 lines (99 loc) · 3.87 KB
Raw

Build Status

#AMP by Example

AMP by Example is a collection of Accelerated Mobile Pages.

Installation

  1. Create a fork of the repository.
  2. Install NodeJS.
  3. Setup the repository.
$ git clone https://github.com/YOUR_GITHUB_NAME/amp-by-example.git
$ cd amp-by-example
$ npm i
$ sudo npm i -g gulp

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 by running gulp:

$ gulp
$ open http://localhost:8000/

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

If your sample is using an experimental component, you can add a metadata section (<!--- ... --->) with the json variables experiment and component, this will skip its validation and add an experimental note with instructions to your sample:

<!---{
  "experiment": true,
  "component": "amp-experimenal-component"
}--->

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

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.