# IMPORTANT: AMP by Example has been merged into amp.dev. All new issues and pull requests should be created [here](https://github.com/ampproject/docs).
# AMP by Example
## Installation
1. Fork the repository.
2. Install [NodeJS](https://nodejs.org). You will need version 4.0.0 or above.
3. Install [Gulp](http://gulpjs.com/) via `npm`. You may need to use `sudo` depending on your Node installation.
```none
$ npm install -g gulp
```
4. Set up the repository:
```none
$ git clone https://github.com/YOUR_GITHUB_NAME/amp-by-example.git
$ cd amp-by-example
$ npm install
```
5. Build and run the site:
```none
$ gulp
```
6. If everything went well, `gulp` should now be running the site on
## 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`:
```none
$ 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:
```none
$ 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:
```none
$ 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:
```none
$ gulp validate
```
Run build to generate all examples:
```none
$ gulp build
```
While working on an example you can start a local webserver with auto-reload on by running `gulp`:
```none
$ gulp
```
Some components, like [amp-live-list](https://github.com/ampproject/amp-by-example/blob/master/src/20_Components/amp-live-list.html) require an additional server endpoint.
## Writing the sample
Use HTML comments (``) to document your sample code:
```html
```
This works for elements in the header as well:
```html
...
```
Every HTML comment creates a separate example section spanning the following HTML element.
```html
```
Nesting comments are not supported:
```html
```
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:
```html
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.
**Colors**
**Spaces**
#### Formatting
You can use [markdown](https://help.github.com/articles/github-flavored-markdown/) to format your documentation:
```html
```
#### Notes, Warnings & Tips
There's a special markup available for callouts:
```
[tip type="default|important|note|read-on"]
Tip!
[/tip]
```
For example:
```
[tip type="important"]
Warning! This might go wrong.
[/tip]
```
#### Hints
If you'd like to add additional information about a single element inside a section, use the ``:
```html
```
This will make the `` 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.
```yaml
```
#### Experimental Features
If your sample is using one or more experimental features, you can add a metadata section (``) with the variable `experiments` to specify which experiments to enable. This will skip its validation and add an experimental note with instructions to your sample:
```yaml
```
#### Preview Mode
Visually rich examples can provide a preview mode like [this](https://ampbyexample.com/samples_templates/news_article/preview/). Enable via metadata in the sample:
```yaml
```
There is a special preview mode for AMP Ad samples:
```yaml
```
#### 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:
```yaml
```
#### Disabling the Playground
If it doesn't make sense for your sample to provide a playground link, you can disable it:
```yaml
```
## 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](https://cloud.google.com/appengine/docs/flexible/go/download).
2. Run the backend server in watch mode so it will recompile on change.
```none
$ 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:
```none
# 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
### 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](https://github.com/ampproject/amp-by-example/blob/master/templates/css/styles.css) 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 `
**Spaces**
#### Formatting
You can use [markdown](https://help.github.com/articles/github-flavored-markdown/) to format your documentation:
```html