ampproject / amp.dev Goto Github PK

The AMP Project Website.

License: Other

CSS 8.82% JavaScript 16.53% Python 2.27% HTML 56.74% Dockerfile 0.05% Tcl 0.02% SCSS 9.87% Handlebars 0.31% Shell 0.01% EJS 0.12% Jinja 5.25%

amp.dev's Introduction

amp.dev

The official homepage of the AMP Project.

Contributing

We welcome contributions to amp.dev.

Bug reports and feature requests: something missing or not working on amp.dev? Please file an issue here.
Documentation & Guides: see this guide for more information on how to contribute documentation to amp.dev.
Code samples & demos: see this guide for more information on how to contribute sample code to amp.dev.

Note: fixing spelling mistakes and other small changes are often easiest by directly editing the file on Github.

Setup

Note: Setting up amp.dev requires a working Python 3 environment on your machine which might not be easy to get going. You can skip this by using the Docker-based setup.

Requirements

Note: For those intending to conduct development on this repository beyond fixing typos, Linux and macOS are the only currently supported operating systems. Windows is not supported at this time.

Install the LTS version of Node.js. An easy way to do so is by using nvm.
```
$ nvm install --lts
```
If it has not already been done, install Python 3 and ensure pip is properly set up by adding the pip user base binary directory to $PATH.

macOS
1. Install Homebrew.
2. Run the following command to ensure everything is up to date. Xcode version 10.3 or the most recent stable version is required.
```
$ brew doctor
```
3. Run the following command to install Python. Version 3.7 is required at latest.
```
$ brew install python libyaml
```
4. Run the following command to add the pip user base binary directory to $PATH.
```
$ echo "export PATH=\"$(python -m site --user-base)/bin\":\$PATH" >> ~/.bash_profile
```
5. Run the following command for the changes to take effect.
```
$ source ~/.bash_profile
```
Linux (Debian-based)

Note: If using Linux, refer to the section of pip's official documentation titled Ensure you can run pip from the command line for pip installation troubleshooting.
1. Run the following command to add the pip user base binary directory to $PATH.
```
$ echo "export PATH=\"$(python -m site --user-base)/bin\":\$PATH" >> ~/.bashrc
```
2. Run the following command for the changes to take effect.
```
$ source ~/.bashrc
```
3. Run the following command to use a faster YAML parser.
```
$ sudo apt install -y python-yaml libyaml-dev
```
Install Grow, the static site generator used to build amp.dev. Do so by using pip instead of its installer. Using pip will enable importing from the grow package in Python later on.

Note: Be sure to use the pip command associated with Python 3 as Grow 1 depends on Python 3.

Mac

  LDFLAGS="-L$(brew --prefix)/lib" CFLAGS="-I$(brew --prefix)/include" pip3 install --global-option="--with-libyaml" --force pyyaml
  pip3 install --user grow

Linux

 $ pip3 install --global-option="--with-libyaml" --force pyyaml
 $ pip3 install --user grow

Fork & clone the repository

To get started with contributing to amp.dev, you first need to fork the repository. Once you've done that you can clone the repository:

$ git clone https://github.com/YOUR-USERNAME/amp.dev

... and then install the dependencies via NPM:

$ cd amp.dev
$ npm install

Develop

If it's your first time working on amp.dev, it is recommended to bootstrap your local environment. To do so, make sure you have set up a valid GitHub access token in an environment variable named AMP_DOC_TOKEN like so:

$ export AMP_DOC_TOKEN="c59f6..."

This command enables the import from GitHub to run flawlessly. The actual import occurs by running the following command, which will also build the Playground and Boilerplate Generator once.

$ npm run bootstrap

Tip: Due to bad network conditions or GitHub's API rate-limiting there might be errors during import. Try running the above command with the -- --queue-imports flag to prevent them.

You can then start developing in your local environment with the command below. The task will take care of building and copying all files, watching them for changes, and rebuilding them when needed. Beware that changes to the Express backend require the Gulp task to be restarted.

$ npm run develop

This command prints a lot to the shell and will most likely end on Server ready. Press ctrl-c to quit.. Seeing this line means everything went fine so far unless otherwise stated in the logs; the site should be available at http://localhost:8080/. The service running on port 8081 is only Grow rendering the pages.

You can contribute your changes back to the main repository by creating a pull request.

Setup with Docker

We provide a Dockerfile for development based on one of the official Python-images. When using this you can skip setting up Python and a local installation of Grow on your machine. Though make sure you completed all other installation steps, like cloning the repository, installing all Node.js dependencies and exporting a valid GitHub token as outlined in Fork & clone the repository and Develop. When those steps are completed instead of running the project with npm run develop you can build a development Docker image with the followiung command, run from the project root directory:

$ npx gulp developImageBuild

After the image has been successfully built start a container with the following command:

$ npx gulp developContainer

This command also mounts the pages directory, meaning all changes you are doing to any of the markdown files in pages/content are reflected to the container and can be reviewed without rebuilding the image.

Maintenance

Documents

Made changes to a lot of Grow documents at once and not quite sure if all references are still valid? You can run npm run lint:grow to pick up broken ones.

Run a test build

To run a local test build that does all the minifying and vends the static pages instead of proxying them through to Grow you can run:

$ npm run build:local
$ npm run start:local

Tip: For more rapid local testing, it may be preferable to only build a subset of specified locales. Run the following command with --locales being a comma seperated list of locale abbreviations you want to build, e.g. en,fr or even just en.

npm run build:local -- --locales <list of locales>

Build

Caution: starting a build will automatically clean all locations of possible remainings from previous builds. Make sure you don't have anything there that you want to keep - additionally check your working copy for eventual unintended local changes.

npm run build:local -- --locales <list of locales>

To perform a build run the following command with --env being one of the following valid environments: development, local, staging or production:

$ npx gulp build --env <environment>

This command builds all parts of the project and might take a while. Usually, all builds on amp-dev-staging.appspot.com and amp.dev are built using Travis CI. In case you want to reproduce one of those remote builds in your local environment, you can fetch the build artifacts by running:

$ npx gulp fetchArtifacts --travis-build <build_number>

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS-IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

amp.dev's People

Contributors

Stargazers

Watchers

Forkers

narishima-k ditso bigcui bradoyler pmoskovi mterenzio geevi quamsta wintermuting erwinmombay britice andreban camelburrito mikelax prayagverma adamzr dailymotion mdwelsh robertosobachi sebastianbenz avimehta rsobachi pollonamid syntax-ppc yunelee ramteltechnologies jeiwan skyone5 rzhw jmadler dandv honeybadgerdontcare zhouyx nicbarajas adamcbrewer aghassemi saymedia swaaan sathrall ilikethese odino aaroncritchley christosap wesavetheworld tgallant lannka kaddopur benvitale james4388 cwdoh jridgewell navarr syed-haroon kul3r4 namse filisantillan dbs aileen meggin foxsportsaustralia tgfjt serendipitist alphayang cramforce tonyruscoe dracos heltonn mathiasbynens fqj moranji kublaj kmh287 ithinkihaveacat elegeros travis-johnson cloudflare cvializ dfanchon darcardona stephenasamoah dakkad s1ckdark nickgarvey jasti mattiadesiderio bengotow gabebender upperquad rastaturin mattludwig zhangsu uniquelygeneric pearlwang1106 coryphwang jpettitt viktorminator morsssss israelshmueli manmath umh

amp.dev's Issues

Typo in technical_overview.html

Incomplete undecipherable sentence in https://www.ampproject.org/docs/get_started/technical_overview.html:

"For example, If you five ads, ..."

Reorganize extensions

The list of extensions is growing and it probably makes sense to start to group them in some way (e.g. social plugins, video players, …)

I think right now all of them are kind of hidden away (but that might be just me).

Ensure documentation build scripts handle README renaming in amphtml extensions

Currently, .md files intended to be used as READMEs in the amphtml extensions directory are named after the extension (e.g. amp-font.md) rather than README.md.

An issue (ampproject/amphtml#1304) was created in amphtml to rename the extension markdown files to README.md. As mentioned in the issue, for that change to be made, the documentation build scripts need to be modified to accept the renaming.

amp-analytics implementation issues on amproject.org

The hits being sent to google-analytics.com are missing the &cid parameter. This hits are being dropped and not tracked.

example page:
https://www.ampproject.org/docs/reference/extended/amp-analytics.html
using the debug server for https://www.google-analytics.com/debug/collect?v=1&_v=a0&aip=true&_s=&dl=https%3A%2F%2Fwww.ampproject.org%2Fdocs%2Freference%2Fextended%2Famp-analytics.html&dt=amp-analytics&sr=2560x1440&_utmht=14540832363216&jid=&cid=&tid=UA-67833617-1&t=pageview&_r=1&z=0.0456467

{
  "hitParsingResult": [ {
    "valid": false,
    "parserMessage": [ {
      "messageType": "INFO",
      "description": "IP Address from this hit was anonymized to 72.241.118.0.",
      "messageCode": "VALUE_MODIFIED"
    }, {
      "messageType": "INFO",
      "description": "A default value was used for the parameter 'cid'. Please see http://goo.gl/a8d4RP#cid for details.",
      "messageCode": "DEFAULT_VALUE_USED",
      "parameter": "cid"
    }, {
      "messageType": "ERROR",
      "description": "A value is required for parameter 'cid'. Please see http://goo.gl/a8d4RP#cid for details.",
      "messageCode": "VALUE_REQUIRED",
      "parameter": "cid"
    } ],
    "hit": "/debug/collect?v=1\u0026_v=a0\u0026aip=true\u0026_s=\u0026dl=https%3A%2F%2Fwww.ampproject.org%2Fdocs%2Freference%2Fextended%2Famp-analytics.html\u0026dt=amp-analytics\u0026sr=2560x1440\u0026_utmht=1454083780209\u0026jid=\u0026cid=\u0026tid=UA-67833617-1\u0026t=pageview\u0026_r=1\u0026z=0.07820693154899105"
  } ],
  "parserMessage": [ {
    "messageType": "INFO",
    "description": "Found 1 hit in the request."
  } ]
}

Document AMP Dev Channel

All the info is here ampproject/amphtml#2113

I just don't feel qualified to find the right place for this in our docs.

Clarification on <amp-video> tag

I have implemented the tag and it works fine. But I have some questions that I have not been able to find answers for and our Google advocate advised creating an issue .

For a responsive page that has a video, the poster image does not adjust when the viewport size changes while other page components do. That is, when a page is rendered in a larger viewport, a larger image should be able to be specified for the video.
Same comment for the controls. Also, can the controls be customized in any way?
After a video starts to play, if a user starts to scroll through the article and the video is not in the viewport, should the video pause?

Thanks
Ian

Document CSS classes exposed to assist with desktop/mobile cases

AMP provides few CSS classes that we set on the document's body to assist with some typical desktop/mobile cases:

amp-mode-touch - this class is set when we detect touch input
amp-mode-mouse - this class is set when we detect mouse input
amp-mode-keyboard-active - this class is set when the keyboard is active

Mustache syntax gets partially eaten on amp-mustache reference page.

https://www.ampproject.org/docs/reference/extended/amp-mustache.html

Looks like something gets eaten there. E.g.:
"Notice also that because the body of the template has to be specified within the template element, it is impossible to specify expressions - they will always be escaped as. The triple-mustache } has to be used for these cases."

Original text from https://github.com/ampproject/amphtml/blob/master/extensions/amp-mustache/amp-mustache.md:
"Notice also that because the body of the template has to be specified within the template element, it is impossible to specify {{&var}} expressions - they will always be escaped as {{&var}}. The triple-mustache {{{var}}} has to be used for these cases."

This effect applies to this entire page - several of the curly braces get lost in translation.

add list of components with validator status and experiment status

a few people have been asking for this, its a little hard to figure out if something should be turned on in experiments or if something is not in the validator yet which is why they are getting errors.

Each extension should include the script tag that needs to be copy pasted into the page

We can probably auto generate that in jekyll.

I've heard this feedback a lot and it would greatly increase our copy-pasteability.

CC @Meggin @rudygalfi

Extended components list should include amp-analytics

https://www.ampproject.org/docs/reference/extended.html

Hopefully this will happen with the next site push?

Document how to how automatically validate AMP document

as part of CI
or as part of CMS publishing

See original issue

Create paywall/amp-access guide

If I go to our docs thinking I want to implement a paywall, there is no way I find the amp-access page.

Some documents on ampproject.org have validation errors

https://www.ampproject.org/docs/support/faqs.html#development=1
2 errors.

Caused by this tag: <a class="tab hamburger" id="menu-button" href="">≡</a>. The empty href is considered invalid.
Caused by this script tag:

    <script>
    document.getElementById('menu-button').onclick = function() {
      document.getElementsByTagName('header')[0].classList.toggle('menu-open');
      document.querySelector('div.content').classList.toggle('menu-open');
      document.querySelector('nav').classList.toggle('menu-open');
      return false;
    };
    </script>

Publish new AMP codelabs

We are planning on publishing a new set of AMP codelabs, and will make sure ampproject.org points to these codelabs throughout the docs.

Move validation error table to the bottom?

For now our reference pages start with a long list of errors which is not very inviting.

Should we just move them to the end?

https://www.ampproject.org/docs/get_started/create/basic_markup.html should be updated to reflect the new boilerplate

This was mentioned here:
ampproject/amphtml#323

This page has it correct (CTRL+F for amp-boilerplate; there's a script / noscript tag both of which are required):
https://github.com/ampproject/amphtml/blob/master/spec/amp-html-format.md

While the old boilerplate will continue to work for now, we'll want to deprecate it eventually.

Thanks!

ampproject.org front page has deprecated boilerplate

The root document only, as far as I can tell, is using the deprecated style AMP boilerplate, producing validation warnings when using '#development=1'. These will eventually be promoted to errors.

Click-targets within spec file not working well on ampproject.org

I'll post a link to a Google doc in a sec. The markdown formatting of my text talking about markdown is defeating me typing it into this github form. :-)

But I think it would improve usability of the extensions if there was a standard section that was something like:

# Include `amp-frame` on your page
Add `<script async custom-element="amp-iframe" src="https://cdn.ampproject.org/v0/amp-iframe-0.1.js"></script>` in the head of your page.

Jekyll error occurs while generating amp-access-spec documentation

After importing reference docs with import_reference_docs.js, the following error occurs when running jekyll serve:

Configuration file: /<private>/docs/_config.yml
            Source: /<private>/docs
       Destination: /<private>/docs/_site
 Incremental build: disabled. Enable with --incremental
      Generating...
  Liquid Exception: Syntax Error in tag 'highlight' while parsing the following markup: amp-mustache``` 
  Valid syntax: highlight <lang> [linenos] in /<private>/docs/_reference/extended/amp-access-spec.md

AdSense and DoubleClick links on `amp-ad` page are broken

i.e. https://www.ampproject.org/docs/reference/amp-ad.html

The files were moved in ampproject/amphtml@26de70a.

Create new URL checking section in validation errors doc

Group together URL checking errors into a new section, and elaborate in this section on the different checks for different tags.

Also, there's a small bug that I should fix in https://www.ampproject.org/docs/reference/validation_errors.html#mandatory-text-missing-or-incorrect.

Table formatting off-- so make that better too in this PR.

And finally, make sure validation docs in tutorial, etc., point to the new validation errors doc. Cross-referencing quite important for this stuff.

Content container falls below left navigation in Safari 8.x

The AMP docs have a layout issue in older versions of Safari that support Flexbox (Safari 8.x in particular) where the content div wraps below the left navigation. This happens because of a missing legacy display: -webkit-flex; style declaration in the .main rule in _sass/content.scss.

Steps to reproduce:

Navigate to https://www.ampproject.org using Safari 8.x / OS X 10.10.x ("Yosemite")
Click on Docs in the primary navigation menu
Observe that the main content area wraps below the left side navigation menu

See attached screenshot for more detail:

Grammar detail for layout guide.

The title "How AMP layouts its pages" should be written "How AMP lays out its pages" at the top of this section:

https://www.ampproject.org/docs/guides/responsive/control_layout.html#how-amp-layouts-its-pages

Unescaped HTML in docs

There seems to be some broken HTML (unescaped tags) in the AMP documentation main page. In particular, the page contains:

<p>AMP HTML documents MUST:</p>

<ul>
  <li>Start with the doctype &lt;!doctype html&gt;.</li>
  <li>Contain a top-level &lt;html ⚡&gt; tag (&lt;html amp&gt; is accepted as well).</li>
  <li>Contain &lt;head&gt; and &lt;body&gt; tags (They are optional in HTML).</li>
  <li>Contain a <link rel="canonical" href="$SOME_URL" /> tag inside their head that points to the regular HTML version of the AMP HTML document or to itself if no such HTML version exists.</li>
  <li>Contain a <meta charset="utf-8" /> tag as the first child of their head tag.</li>
  <li>Contain a <meta name="viewport" content="width=device-width,minimum-scale=1" /> tag inside their head tag. It’s also recommended to include initial-scale=1.</li>
  <li>Contain a <script async="" src="https://cdn.ampproject.org/v0.js"></script> tag as the last element in their head (this includes and loads the AMP JS library).</li>
  <li>Contain <style>body {opacity: 0}</style><noscript><style>body {opacity: 1}</style></noscript> in their head tag.</li>
</ul>

See e.g. <style>body {opacity: 0}</style><noscript>

CC @Meggin @pbakaus

Guide for AMP Analytics (incl. amp-analytics and amp-pixel)

Should touch on these points:

Capabilities of amp-pixel vs. amp-analytics. Why use one over the other?
Components are designed to work whether you're interested in collecting for yourself (owned ingestion endpoint) or want to transmit the data to a 3P (e.g. analytics provider for reporting, dashboards, etc.)
Basic overview of how amp-pixel works technically and how amp-analytics works technically (talk about how amp-analytics uses a "measure once, report to many" approach)
Guide to getting a basic amp-analytics request set up
How amp-analytics works if you want to send the data to a vendor; talk about vendor configuration
Link to a reference on what to do if you are a vendor and want to add a vendor config
Guides on how to use various attributes of amp-analytics and what use cases they address
Talk about client identifier

cc @Meggin

ampproject.org documentation does weird highlighting of punctuation like ":"

See screenshot. Would prefer if this just rendered like normal code text.

Table for control_layout is not well formatted on ampproject.org

The table for control_layout is hard to read:
https://www.ampproject.org/docs/guides/responsive/control_layout.html

It looks fine on GitHub.
https://github.com/ampproject/docs/blob/master/_guides/responsive/control_layout.md

Desktop screenshot:

Mobile web screenshot:

GitHub mobile web screenshot:

Lets not advertise iframes so front and center

As in this page https://www.ampproject.org/docs/guides/amp_replacements.html#display-an-iframe

Also the example is incomplete, because it is missing the needed script tag, so copy pasting from the docs would be broken.

jekyll error in pages_toc.html

Running jekyll serve as per the README, I'm encountering:

Liquid Exception: undefined method `sort' for nil:NilClass in _includes/pages_toc.html, included in _get_started/create_page.md
jekyll 2.5.3 | Error:  undefined method `sort' for nil:NilClass

Favicon.ico

Update for AMP HTML documentation regarding structured data

The structured data example shown at https://www.ampproject.org/docs/get_started/create/basic_markup.html isn't sufficient to validate in the structured data testing tool.

We should consider replacing this with the code in the example on:
https://developers.google.com/structured-data/carousels/top-stories

The media attribute example should show how to select an image based on screen width

The current example is kind of useless. Usually you want e.g. one image with a max-width and one with a min-width, so that only one is shown.

Click a TOC item does not add hash to URL and jumps below headline.

To repro go to
https://www.ampproject.org/docs/guides/responsive/control_layout.html
and click one of the lower TOC items.

Contrast is unreadably low

E.g. https://www.ampproject.org/docs/support/faqs.html#how-do-accelerated-mobile-pages-work

As a visually impaired person, the text on that page is nearly invisible. Even my coworkers with normal vision report that it is hard for them to read. Please adjust the contrast to meet the usual web accessiblity guidelines.

Grey text on light grey background is very difficult to read for the vision impaired

Options for a higher contrast (and other accessibility options) are highly desirable.

amp-img with layout responsive not visible

Using the Skeleton grid (http://getskeleton.com/) in my amp-html demo, I've set amp-img to layout=responsive because the images aspect ratio was being distorted on resize. With layout=responsive, this img width and height are changes to 0 and the image is not visible. Demo at pos.88k.com.tw (up temporarily)

What happened to this link!?

https://github.com/ampproject/docs/blob/master/docs/guides/validate.html

It's the last link on this page: https://github.com/ampproject/docs/blob/master/_get_started/about-amp.md

Update FAQ page

At https://www.ampproject.org/docs/support/faqs.html, these sections should be updated:

Why does the Accelerated Mobile Pages Project take an open source approach
analytics
paywalled content

Plus generally the future tense of "How will X work" should become present - "How does X work".

List known platforms and any specific docs and support links

Give straightforward explanation how to make a responsive image

It is in here, but really dug under lots of detail that is almost never necessary.
https://www.ampproject.org/docs/guides/responsive_amp.html

Better document how layouts work including 'heights'

The current doc, https://www.ampproject.org/docs/guides/responsive/control_layout.html, does a decent early job explaining layouts in AMP.

But it definitely needs to be updated to cover 'heights' (wherever sizes documented).

It also could do more to talk about common layout patterns for amp tags (like how container isn't supported in most, and some have nodisplay only, and how default behaviors work, etc.).

cdn.ampproject.org/v0.js requirement?

According to https://www.ampproject.org/docs/get_started/create/basic_markup.html a requirement to being AMP compliant is to include <script async src="https://cdn.ampproject.org/v0.js"></script> right before the </head> tag. Could not the AMP JS code be served via a CDN like Akamai other than cdn.ampproject.org which might improve availability to clients? If a site could host the AMP JS with their other CDN content then CORS setup could would seem remain intact. If Google should rank pages based upon AMP compliance, this would seem to tie page ranking to another Google product, that being cdn.ampproject.org which, as I understand it, is served via Google's CDN.

Is this an ease of implementation detail? Saying the script tag right before </head> must be literally https://cdn.ampproject.org/v0.js? If so, then what about v1.js? Or is the test a regular expression? Could it not be that the script tag right before </head> somehow otherwise indicate that it is AMP JS by say the src attribute containing ampproject or there being an amp attribute included, ex <script async amp src="https://cdn.somedomain.com/v0.js"></script>

Requiring AMP JS code before </head> make sense and having it available via cdn.ampproject.org is great. However, forcing the use of a specific seems counter to an open web. Thoughts?

extensions/amp-live-list/0.1
- amp-live-list does not have type.file contents.

To reproduce:

follow README

TypeError: Cannot read property 'path' of undefined
    at /Users/jellis/dev/projects/yieldbot/amphtml.docs/_scripts/import_reference_docs.js:167:29
    at /Users/jellis/dev/projects/yieldbot/amphtml.docs/node_modules/octonode/lib/octonode/repo.js:471:18
    at Client.errorHandle (/Users/jellis/dev/projects/yieldbot/amphtml.docs/node_modules/octonode/lib/octonode/client.js:196:14)
    at Request._callback (/Users/jellis/dev/projects/yieldbot/amphtml.docs/node_modules/octonode/lib/octonode/client.js:210:24)
    at Request.self.callback (/Users/jellis/dev/projects/yieldbot/amphtml.docs/node_modules/request/request.js:373:22)
    at emitTwo (events.js:100:13)
    at Request.emit (events.js:185:7)
    at Request.<anonymous> (/Users/jellis/dev/projects/yieldbot/amphtml.docs/node_modules/request/request.js:1318:14)
    at emitOne (events.js:95:20)
    at Request.emit (events.js:182:7)

Invalid word breaking

Word breaking is invalid, unacceptable. The culprit must be hiding somewhere in these lines.