Add filtering for AMP examples (ampproject#2494)

getzaymo · Jul 16, 2019 · 29a2462 · 29a2462
1 parent f474911
commit 29a2462
Show file tree

Hide file tree

Showing 3 changed files with 65 additions and 45 deletions.
diff --git a/contributing/documentation.md b/contributing/documentation.md
@@ -17,22 +17,22 @@ chaptered: true|false
 The documents inside the *pages* package are Grow documents that use the [built-in fields](http://grow.io/docs/documents/#built-in-fields) and some additional ones that are used to categorize them:
 
 ```yaml
-- formats [default: websites,ads,email,stories]:
+formats [default: websites,ads,email,stories]:
   - websites
   - ads
   - email
   - stories
-- status [default: production]:
+status [default: production]:
   - experimental
   - canary
   - production
-- validAmp [default: true]
+validAmp [default: true]
   - true
   - false
-- draft [default: true]
+draft [default: true]
   - true
   - false
-- tags [default: '']
+tags [default: '']
   - ads-analytics
   - dynamic-content
   - layout
@@ -47,9 +47,9 @@ By the categorization via the `formats` list in the frontmatter the user is able
 
 If the document has a specific path that is not getting inherited from the `_blueprint.yaml` also make sure to set a matching path. Same example: `index.md` has `$path: /category.html` then `index.ads.md` needs to have `$path: /category.ads.html`. Otherwise the build process is not able to match the base and the filtered variant. To not have double navigation items make sure to also give `$hidden: true` to the filtered variant.
 
-### Format filtered paragraphs 
+### Format filtered paragraphs
 Documents will be relevant to multiple formats on a broad scope, but may contain sections and paragraphs that are not accurate for all formats listed in the frontmatter. You can wrap paragraphs in a filter to hide or show them, depending on what format the user has selected.
- 
+
 ```
 [filter formats="websites"]
 This is only visible for [websites](?format=websites).
@@ -111,13 +111,13 @@ The Link is optional and will create a button inside the stage.
 
 A list of links that will expand to a row of cards that link to the document.
 
-### Code Samples 
+### Code Samples
 Code samples are placed inside sets of three backticks. The sourcecode language specified at the end of the first backtick set.
 
 <pre>
 ```html
   // code sample
-```  
+```
 
 ```css
   // code sample
@@ -143,7 +143,7 @@ If your code contains double curly braces, which often is the case if you use am
 Python-Markdown has some limitations. Use the following syntax when including code samples in lists:
 <pre>
   <code>
-  1. First: 
+  1. First:
     [sourcecode:html]
       &lt;html&gt;
           &lt;p&gt;Indented content.&lt;/p&gt;

diff --git a/contributing/samples.md b/contributing/samples.md
@@ -1,6 +1,6 @@
 ## Creating a new sample
 
-Samples live in `examples/source`. Pick one of the existing category folders. 
+Samples live in `examples/source`. Pick one of the existing category folders.
 
 If your sample can live in a single html file, create a new `*.html` in  one of the sample category folders:
 
@@ -18,16 +18,16 @@ $ vim examples/source/1.components/amp-awesome/api.js
 
 If your sample, does not fit into one of the existing categories, please [create an issue](https://github.com/ampproject/docs/issues/new) first and ask for feedback.
 
-[Here is a sample template](https://gist.github.com/sebastianbenz/45d3dae499f35dedb65e01546356ff7a) you can use to get started. 
+[Here is a sample template](https://gist.github.com/sebastianbenz/45d3dae499f35dedb65e01546356ff7a) you can use to get started.
 
 ## Frontmatter
 
 Samples can define additional metadata (such as author name or supported AMP formats) via a YAML frontmatter. Here is a template to get you started:
 
 ```
 <!---
-- author: your-github-user-name
-- formats
+author: your-github-user-name
+formats:
   - websites
 --->
 ```
@@ -37,7 +37,7 @@ Samples can define additional metadata (such as author name or supported AMP for
 You must list all the supported AMP formats for your sample. If your sample is specific AMP format, define that single format.
 
 ```
-- formats
+formats
   - email
 ```
 
@@ -51,18 +51,18 @@ experiments:
 Other supported flags are:
 
 ```yaml
-- formats # [default: websites,ads,email,stories]:
+formats # [default: websites,ads,email,stories]:
   - websites
   - ads
   - email
   - stories
-- validAmp # [default: true]
+validAmp # [default: true]
   - true
   - false
-- draft # [default: true]
+draft # [default: true]
   - true
   - false
-- tags # [default: '']
+tags # [default: '']
   - ads-analytics
   - dynamic-content
   - layout
@@ -220,13 +220,28 @@ If you'd like to add additional information about a single element inside a sect
 
 This will make the `<input>` element clickable, with the additional explanation appearing on click.
 
+#### Filtering
+
+If a section is only applicable to one format, use `@format(comma-separated-list)`
+anywhere in the section comment to indicate that section is only applicable to
+the format(s) listed.
+
+```html
+<!--
+  The following code only applies to AMP emails.
+
+  @format(email)
+-->
+<p>Hello, world!</p>
+```
+
 ### Adding backend functionality
 
 Before writing your own API endpoint, please take a look at the [existing generic API endpoints](https://github.com/ampproject/docs/tree/future/examples/api), maybe you can re-use one of them.
 
 Sample specific backend endpoints live in a JS file inside the sample folder. They are implemented via [Express routing](https://expressjs.com/en/guide/routing.html). You can address your API endpoints relative to your sample location, e.g. `<amp-list src="you-api-route' ...>`.
 
-Here is a template to get you started. 
+Here is a template to get you started.
 
 ```
 /**

diff --git a/platform/lib/build/samplesBuilder.js b/platform/lib/build/samplesBuilder.js
@@ -236,9 +236,9 @@ class SamplesBuilder {
     parsedSample.route = this._getDocumentationRoute(sample);
 
     // Rewrite some markdown to be consumable by Grow
-    for (const index in parsedSample.document.sections) {
+    for (const section of parsedSample.document.sections) {
       // Replace GitHub sourcecode syntax by python-markdown
-      let markdown = parsedSample.document.sections[index].doc_;
+      let markdown = section.doc_;
       markdown = MarkdownDocument.rewriteCodeBlocks(markdown);
       markdown = MarkdownDocument.escapeMustacheTags(markdown);
 
@@ -268,7 +268,7 @@ class SamplesBuilder {
         markdown = markdown.replace(hash, codeBlocks[hash]);
       }
 
-      parsedSample.document.sections[index].doc_ = markdown;
+      section.doc_ = markdown;
     }
 
     return parsedSample;
@@ -281,22 +281,23 @@ class SamplesBuilder {
    * @param {Object} parsedSample The parsed sample
    */
   _addToSitemap(sample, parsedSample) {
-    const format = this._getSampleFormat(parsedSample);
-    const formatCategories = this._sitemap[format] || {};
+    for (const format of this._getSampleFormats(parsedSample)) {
+      const formatCategories = this._sitemap[format] || {};
 
-    const category = require(path.join(SAMPLE_SRC, this._getCategory(sample, true), 'index.json'));
-    const categorySamples = formatCategories[category.publicName] || {
-      'name': category.publicName,
-      'examples': [],
-    };
-    categorySamples.examples.push({
-      'title': parsedSample.document.title,
-      'url': `${config.getHost(config.hosts.preview)}` +
-          this._getSourceRoute(sample),
-    });
+      const category = require(path.join(SAMPLE_SRC, this._getCategory(sample, true), 'index.json'));
+      const categorySamples = formatCategories[category.publicName] || {
+        'name': category.publicName,
+        'examples': [],
+      };
+      categorySamples.examples.push({
+        'title': parsedSample.document.title,
+        'url': `${config.getHost(config.hosts.preview)}` +
+            this._getSourceRoute(sample),
+      });
 
-    formatCategories[category.publicName] = categorySamples;
-    this._sitemap[format] = formatCategories;
+      formatCategories[category.publicName] = categorySamples;
+      this._sitemap[format] = formatCategories;
+    }
   }
 
   /**
@@ -477,7 +478,7 @@ class SamplesBuilder {
    */
   _getTeaserData(parsedSample) {
     const teaserData = {};
-    teaserData.formats = [this._getSampleFormat(parsedSample)];
+    teaserData.formats = this._getSampleFormats(parsedSample);
     teaserData.used_components = this._getUsedComponents(parsedSample);
 
     if (parsedSample.document.metadata.teaserImage) {
@@ -492,21 +493,25 @@ class SamplesBuilder {
   /**
    * Used to determine the sample format by string
    * @param  {Object} parsedSample
-   * @return {string}
+   * @return {Array<string>}
    */
-  _getSampleFormat(parsedSample) {
+  _getSampleFormats(parsedSample) {
+    if (parsedSample.document.metadata.formats) {
+      return parsedSample.document.metadata.formats;
+    }
+
     if (parsedSample.document.isAmpStory) {
-      return 'stories';
+      return ['stories'];
     }
     if (parsedSample.document.isAmpAds) {
-      return 'ads';
+      return ['ads'];
     }
     if (parsedSample.document.isAmpEmail) {
-      return 'email';
+      return ['email'];
     }
 
     // Use websites as fallback as isAmpWebsites could be true for all formats
-    return 'websites';
+    return ['websites'];
   }
 
   /**
@@ -657,7 +662,7 @@ class SamplesBuilder {
         '$localization': {
           'path': `/{locale}${this._getPreviewRoute(sample)}`,
         },
-        'formats': [this._getSampleFormat(parsedSample)],
+        'formats': this._getSampleFormats(parsedSample),
         'source': this._getSourceRoute(sample),
         'embed': this._getEmbedRoute(sample),
       }, {'lineWidth': 500}),