Skip to content

Latest commit

 

History

History
184 lines (119 loc) · 11.3 KB

ampproject-files-build-process.md

File metadata and controls

184 lines (119 loc) · 11.3 KB
Raw

AMPProject.org files & build process

This document provides information on how the site is built, the purpose of certain files, and other important information if you're working with the ampproject.org site.

Contents

TL;DR;

Repository content

The contents for the ampproject.org site can be found in the ampproject/docs GitHub repo. We use mostly Markdown, HTML, and .yaml files for the docs you see on the site. The files in the docs repo are organized per Grow's recommended directory structure.

├──  /assets                         # Visual assets
├──  /content                        # All the content for the site
|    ├──  /docs                      # Content for "Docs" section
|         ├──  /_blueprint.yaml      # Blueprint for collection
|         └──   /....md              # Content document
|    ├──  /includes                  # Dynamic content to include in pages
|    ├──  /latest                    # Content for "Latest" section
|    ├──  /learn                     # Content for"About" section
|    ├──  /pages                     # HTML templates for one-off pages (home page, 404)
|    └──  /reference                 # Content for"Reference" section
|    └──  /support                   # Content for"Support" section
|
├──  /contributing                   # Github details on contributing
├──  /examples                       # Source code for embedded samples
├──  /pwa                            # PWA implementation for site
├──  /scripts                        # Scripts for automated tasks
|    ├──  component_categories.json  # Associate amp components with category
|    ├──  import_roadmap.js          # Imports roadmap from AMPHTML repo
|    ├──  import_docs.js             # Imports docs from AMPHTML repo
|    ├──  import_docs.json           # Specific docs to import
|    ├──  update_blog_links.js       # Gets blogs WP and formats for site
|    ├──  update_platforms_page.js   # Updates platforms page with latest
|    └──  update_tweets.js           # Updates tweets section of site
├──  /translations                   # Extracted message cat. for localization
├──  /tutorial_source                # Source code for tutorials
└──  /views                          # Front-end template views

Most of the files for the ampproject.org site can be found in the docs repo, but we also import docs from the amphtml repo (these are the docs you see in the Reference section, for example, amp-img). More details about importing below.

Imported docs from AMPHTML repo

A number of docs original source are located in the AMPHTML repo that we import into the build process (via import_docs.js) so that they appear on the ampproject.org site. These docs include:

Why do we import instead of having the canonical file in the docs repo? Keeping the doc with source code is good for findability, smoother PRs, and incentive for developers to maintain docs.

Testing AMPHTML changes in your local ampproject site

If you've made changes to docs in the AMPHTML repo (e.g., fixing a component doc), and you want to see how your changes appear in ampproject (before submitting your PR), you'll need to:

  1. Make sure you have the AMPHTML repository on your local machine, and check out the branch with your changes.
  2. Add the following to your path: export AMP_DOC_LOCAL_PATH=~/amphtml (change the path to whatever your amphtml directory is).
  3. Run grow run to run the local instance of ampproject.

If you want to switch back to pointing to the AMPHTML production docs, remove the AMP_DOC_LOCAL_PATH path (comment it out) and rebuild your local instance of ampproject.

Build process

To build the site, we use Grow, which generates HTML files from the markdown files and stores them in the "build" directory. As part of the build, we use a gulp preprocessor to run additional tasks, like formatting markup, cleaning up markup, importing docs from amphtml repo (details in the Gulp preprocess tasks section.

Instructions for building locally: how-to-build-the-site

Branches

There are two main branches that we use to build and maintain the ampproject.org site:

------------- Production   <--  reflects what's running on www.ampproject.org
    \
     \------- Master       <-- where code changes are made, and pull requests are made

Continuous build

The ampproject.org site has a CI build process that runs on Travis CI. Requirements are defined in .travis.yml.

  • Every commit merged into Master kicks off a build of the Master branch. If the build passes, the changes are reflected on the staging site.
  • @bpaduch and @pbakaus manually merge commits from Master into the Production branch, which kicks off a Production build. If the build passes, the changes are live on www.ampproject.org.
  • Each night there's a Production build based off the Production branch.

Gulp preprocess tasks

The following gulp tasks are performed in a build (details are in gulpfile.js):

Authoring

Notes and tips

To write a nicely formatted note or tip, simply write it as single line, prefaced with "Tip:", "Note:", "Learn more" or "Caution:" (also works for localized versions), like so:

Tip: This will turn into a nicely formatted block. I can contain any kind of markdown, like [links](https://ampproject.org).

In situations where you need multiple lines, or if you want to customize the title, use the macro syntax of Grow, like so:

{% call callout('Here's a fancy tip', type='success') %}
Tips can have multiple lines.

Unfortunately you have to write out the macro then.
{% endcall %}

Here, the first attribute to the callout function can be customized to any string, the type accepts either none, note, caution, warning, success or read.

Images

Images should be written with the following macro (as standard Markdown syntax will produce invalid <img> tags, which are invalid in AMP):

{{ image('/static/img/docs/tutorials/amp-live-list-ampbyexample.png', 700, 1441, align='right third', caption='Optional caption', alt='optional alt text') }}

Animated images

Animated images should be written with the following macro (as standard Markdown syntax will produce invalid <img> tags, which are invalid in AMP):

{{ anim('anim.gif', 700, 1441, 'anim-placeholder.png', align='right third', alt='optional alt text') }}

YouTube

Include YouTube videos with the following macro:

{{ youtube('y6kA3u3GIws', 480, 270, caption='Watch UpperQuad talk about the AMPproject site redesign, including the challenges of using AMP for the first time.') }}

Video

Include generic HTML5 video with the following macro:

{{ video('video.mp4', 480, 270, 'poster.jpg', caption='optional caption', autoplay='1', loop='1', controls='1') }}

autoplay, loop, controls are all optional and off by default.

Localization

As part of the Grow syntax and build process, we provide localized version of the site.

Hosting

The ampproject.org site is hosted on Firebase.