From f64a662df89bddf8342c70474df8168f39b4c5dd Mon Sep 17 00:00:00 2001 From: Raghu Simha Date: Tue, 1 Aug 2017 15:52:00 -0400 Subject: [PATCH] Reformat domain links in documentation files and remove unnecessary link checker whitelist filters --- ads/google/a4a/docs/Network-Impl-Guide.md | 28 +++++++++---------- build-system/tasks/check-links.js | 8 ------ extensions/amp-ad/amp-ad.md | 8 +++--- extensions/amp-dailymotion/amp-dailymotion.md | 2 +- tools/experiments/README.md | 4 +-- 5 files changed, 21 insertions(+), 29 deletions(-) diff --git a/ads/google/a4a/docs/Network-Impl-Guide.md b/ads/google/a4a/docs/Network-Impl-Guide.md index 4a4bfbe674a4..7b4214ba6f9f 100644 --- a/ads/google/a4a/docs/Network-Impl-Guide.md +++ b/ads/google/a4a/docs/Network-Impl-Guide.md @@ -9,17 +9,17 @@ # Objective -Outline requirements and steps for ad network to implement Fast Fetch for early ad request and support for AMP Ads returned by the ad network to be given preferential rendering. +Outline requirements and steps for ad network to implement Fast Fetch for early ad request and support for AMP Ads returned by the ad network to be given preferential rendering. # Background Relevant design documents: [A4A Readme](./a4a-readme.md), [A4A Format Guide](https://github.com/ampproject/amphtml/blob/master/extensions/amp-a4a/amp-a4a-format.md) & [intent to implement](https://github.com/ampproject/amphtml/issues/3133). -If you haven’t already, please read the A4A Readme to learn about why all networks should implement Fast Fetch. +If you haven’t already, please read the A4A Readme to learn about why all networks should implement Fast Fetch. # Overview -Fast Fetch provides preferential treatment to Verified AMP Ads over Legacy Ads, unlike the current 3P rendering flow which treats AMP Ads and Legacy Ads the same. Within Fast Fetch, if an ad fails validation, that ad is wrapped in a cross-domain iframe to sandbox it from the rest of the AMP document. Conversely, an AMP Ad passing validation is written directly into the page. Fast Fetch handles both AMP and non-AMP ads; no additional ad requests are required for ads that fail validation. +Fast Fetch provides preferential treatment to Verified AMP Ads over Legacy Ads, unlike the current 3P rendering flow which treats AMP Ads and Legacy Ads the same. Within Fast Fetch, if an ad fails validation, that ad is wrapped in a cross-domain iframe to sandbox it from the rest of the AMP document. Conversely, an AMP Ad passing validation is written directly into the page. Fast Fetch handles both AMP and non-AMP ads; no additional ad requests are required for ads that fail validation. In order to support Fast Fetch, ad networks will be required to implement the following: @@ -51,7 +51,7 @@ Client side verification of the signature, and thus preferential rendering, requ Fast Fetch requires that the ad request be sent via [XHR CORS](https://www.w3.org/TR/cors/) as this allows for direct communication with the ad network without the possibility of custom javascript execution (e.g. iframe or JSONP). XHR CORS requires a preflight request where the response needs to indicate if the request is allowed by including the following headers in the response:: -* "Access-Control-Allow-Origin" with value matching the value of the request "Origin" header only if the origin domain is allowed ("Note that requests from pages hosted on the Google AMP Cache will have a value matching the domain [https://cdn.ampproject.org](https://cdn.ampproject.org)"). +* "Access-Control-Allow-Origin" with value matching the value of the request "Origin" header only if the origin domain is allowed ("Note that requests from pages hosted on the Google AMP Cache will have a value matching the domain `https://cdn.ampproject.org`"). * "AMP-Access-Control-Allow-Source-Origin" with value matching the value of the request parameter "__amp_source_origin" which is [added](https://github.com/ampproject/amphtml/blob/master/src/service/xhr-impl.js#L103) by the AMP HTML runtime and matches the origin of the request had the page not been served from [Google AMP Cache](https://www.ampproject.org/docs/get_started/about-amp.html) (the originating source of the page). Ad network can use this to prevent access by particular publisher domains where lack of response header will cause the response to be [dropped](https://github.com/ampproject/amphtml/blob/master/src/service/xhr-impl.js#L137) by the AMP HTML runtime. @@ -61,13 +61,13 @@ Fast Fetch requires that the ad request be sent via [XHR CORS](https://www.w3.or ## A4A Extension Implementation -The [AMP Ad](https://github.com/ampproject/amphtml/blob/master/extensions/amp-ad/amp-ad.md) element differentiates between different ad network implementations via the type attribute, e.g. the following amp-ad will utilize DoubleClick: +The [AMP Ad](https://github.com/ampproject/amphtml/blob/master/extensions/amp-ad/amp-ad.md) element differentiates between different ad network implementations via the type attribute, e.g. the following amp-ad will utilize DoubleClick: To create an ad network implementation, the following steps must be taken: -Create a new extension within the extensions section in the AMP HTML Github [repository](https://github.com/ampproject/amphtml) whose path and name match the type attribute given for amp ad element as follows: +Create a new extension within the extensions section in the AMP HTML Github [repository](https://github.com/ampproject/amphtml) whose path and name match the type attribute given for amp ad element as follows: ![Image of File Hierarchy](./2.png) Figure 2: A4A Extension File Hierarchy @@ -88,7 +88,7 @@ getAdUrl() - must construct and return the ad url for ad request. ``` -Examples of network implementations can be seen for [DoubleClick](https://github.com/ampproject/amphtml/blob/master/extensions/amp-ad-network-doubleclick-impl/0.1/amp-ad-network-doubleclick-impl.js) and [AdSense](https://github.com/ampproject/amphtml/blob/master/extensions/amp-ad-network-adsense-impl/0.1/amp-ad-network-adsense-impl.js). +Examples of network implementations can be seen for [DoubleClick](https://github.com/ampproject/amphtml/blob/master/extensions/amp-ad-network-doubleclick-impl/0.1/amp-ad-network-doubleclick-impl.js) and [AdSense](https://github.com/ampproject/amphtml/blob/master/extensions/amp-ad-network-adsense-impl/0.1/amp-ad-network-adsense-impl.js). Usage of getAdUrl can be seen within the this.adPromise_ promise chain in [amp-a4a.js](https://github.com/ampproject/amphtml/blob/master/extensions/amp-a4a/0.1/amp-a4a.js) @@ -96,23 +96,23 @@ Usage of getAdUrl can be seen within the this.adPromise_ promise chain in [amp-a *See Figure 1: Part A* -Must implement and export following function. +Must implement and export following function. ``` javascript IsA4AEnabled(win, element) // @param (Window) win Window where AMP runtime is running. // @param (HTML Element) element ****The amp-ad element. - // @return (boolean) Whether or not A4A should be used in this context. + // @return (boolean) Whether or not A4A should be used in this context. ``` -Once this file is implemented, [amphtml/ads/_a4a-config.js](https://github.com/ampproject/amphtml/blob/master/ads/_a4a-config.js) must also be updated. Specifically, `IsA4AEnabled()` must be imported, and it must be mapped to the ad network type in the a4aRegistry mapping. +Once this file is implemented, [amphtml/ads/_a4a-config.js](https://github.com/ampproject/amphtml/blob/master/ads/_a4a-config.js) must also be updated. Specifically, `IsA4AEnabled()` must be imported, and it must be mapped to the ad network type in the a4aRegistry mapping. ``` javascript /**amphtml/ads/_a4a-config.js */ … import { IsA4AEnabled -} from ‘../extensions/amp-ad--impl/0.1/-a4a-config’; +} from ‘../extensions/amp-ad--impl/0.1/-a4a-config’; … export const a4aRegistry = map({ … @@ -127,13 +127,13 @@ Usage of DoubleClick and AdSense configs can be seen in [_a4a-config.js](https:/ ### `amp-ad-network--impl-internal.md` -Documentation for ad network amp-ad type. Please thoroughly document the usage of your implementation. +Documentation for ad network amp-ad type. Please thoroughly document the usage of your implementation. Examples can be seen for [DoubleClick](https://github.com/ampproject/amphtml/blob/master/extensions/amp-ad-network-doubleclick-impl/amp-ad-network-doubleclick-impl-internal.md) and [AdSense](https://github.com/ampproject/amphtml/blob/master/extensions/amp-ad-network-adsense-impl/amp-ad-network-adsense-impl-internal.md). ### `test-amp-ad-network--impl.js` -Please write thorough testing for your AMP ad network implementation. +Please write thorough testing for your AMP ad network implementation. ## Ad Network Checklist @@ -157,4 +157,4 @@ Please write thorough testing for your AMP ad network implementation. * Tests written in `test-amp-ad-network--impl.js` -* Pull request merged to master +* Pull request merged to master diff --git a/build-system/tasks/check-links.js b/build-system/tasks/check-links.js index 7853b886106a..06972eed7e78 100644 --- a/build-system/tasks/check-links.js +++ b/build-system/tasks/check-links.js @@ -149,17 +149,9 @@ function filterWhitelistedLinks(markdown) { // Links in script tags (illustrative, and not always valid) filteredMarkdown = filteredMarkdown.replace(/src="http.*?"/g, ''); - // Direct links to the https://cdn.ampproject.org domain (not a valid page) - filteredMarkdown = - filteredMarkdown.replace(/https:\/\/cdn\.ampproject\.org(?!\/)/g, ''); - // Links inside a block (illustrative, and not always valid) filteredMarkdown = filteredMarkdown.replace(/(.*?)<\/code>/g, ''); - // Dailymotion link that is marked dead in Travis CI - filteredMarkdown = filteredMarkdown.replace( - /https:\/\/developer\.dailymotion\.com\/player#player-parameters/g, ''); - // After all whitelisting is done, clean up any remaining empty blocks bounded // by backticks. Otherwise, `` will be treated as the start of a code block // and confuse the link extractor. diff --git a/extensions/amp-ad/amp-ad.md b/extensions/amp-ad/amp-ad.md index 3327fdca2793..3c95fc9ff80e 100644 --- a/extensions/amp-ad/amp-ad.md +++ b/extensions/amp-ad/amp-ad.md @@ -59,7 +59,7 @@ The `` requires width and height values to be specified according to the resizable src="https://ampproject-b5f4c.firebaseapp.com/examples/ampad.basic.embed.html">
Show full code
-
+
@@ -79,7 +79,7 @@ Most ad networks require further configuration, which can be passed to the netwo ##### data-vars-foo-bar -Attributes starting with `data-vars-` are reserved for [`amp-analytics` vars](https://github.com/ampproject/amphtml/blob/master/extensions/amp-analytics/analytics-vars.md#variables-as-data-attribute). +Attributes starting with `data-vars-` are reserved for [`amp-analytics` vars](https://github.com/ampproject/amphtml/blob/master/extensions/amp-analytics/analytics-vars.md#variables-as-data-attribute). ##### json (optional) @@ -110,7 +110,7 @@ Optionally, `amp-ad` supports a child element with the `placeholder` attribute. ## No ad available -The `amp-ad` component supports a child element with the `fallback` attribute. If supported by the ad network, the fallback element is shown if no ad is available for this slot. +The `amp-ad` component supports a child element with the `fallback` attribute. If supported by the ad network, the fallback element is shown if no ad is available for this slot. If there is no fallback element available, the `amp-ad` element is collapsed (that is, set to `display: none`) if the ad sends a message that the ad slot cannot be filled and AMP determines that this operation can be performed without affecting the user's scroll position. @@ -151,7 +151,7 @@ The `content` attribute of the meta tag is the absolute URL to your copy of the Iframes should also enforce that they are only iframed into origins that they expect to be iframed into. The origins would be: - your own origins -- https://cdn.ampproject.org for the AMP cache +- `https://cdn.ampproject.org` for the AMP cache In the case of the AMP cache you also need to check that the "source origin" (origin of the document served by cdn.ampproject.org) is one of your origins. diff --git a/extensions/amp-dailymotion/amp-dailymotion.md b/extensions/amp-dailymotion/amp-dailymotion.md index 873492e41f69..5136ddf49fbf 100644 --- a/extensions/amp-dailymotion/amp-dailymotion.md +++ b/extensions/amp-dailymotion/amp-dailymotion.md @@ -120,7 +120,7 @@ Keys and values will be URI encoded. * `data-param-origin="example.com"` -Please read [Dailymotion's video player documentation](https://developer.dailymotion.com/player#player-parameters) to know more about parameters and options. +Please read [Dailymotion\'s video player documentation](https://developer.dailymotion.com/player#player-parameters) to know more about parameters and options. ##### common attributes diff --git a/tools/experiments/README.md b/tools/experiments/README.md index 4a12ddeeef99..1a06ecf28aff 100644 --- a/tools/experiments/README.md +++ b/tools/experiments/README.md @@ -6,11 +6,11 @@ Developers and users can opt-in into these features before they are fully releas ## Enable an experiment for yourself -Experimental components can be served from [https://cdn.ampproject.org](https://cdn.ampproject.org) or any other domain. +Experimental components can be served from `https://cdn.ampproject.org` or any other domain. ### Served from cdn.ampproject.org -For content served from [https://cdn.ampproject.org](https://cdn.ampproject.org), go to the [AMP experiments page](https://cdn.ampproject.org/experiments.html) and enable (or disable) any experimental component by toggling them on (or off). Opting in will set a cookie on your browser that will enable the experiment on all AMP pages served through the Google AMP Cache. +For content served from `https://cdn.ampproject.org`, go to the [AMP experiments page](https://cdn.ampproject.org/experiments.html) and enable (or disable) any experimental component by toggling them on (or off). Opting in will set a cookie on your browser that will enable the experiment on all AMP pages served through the Google AMP Cache. ### Served from other domains