📖 Move AMP documentation from spec/ to docs/spec/ (#34160)

.github/ISSUE_TEMPLATE/intent-to-deprecate--i2d-.md

@@ -10,7 +10,7 @@ assignees: ''
 <!--
 Replace/remove all of the text in brackets, including this text.
 
-See https://github.com/ampproject/amphtml/blob/main/spec/amp-versioning-policy.md for details on AMP's deprecation policy, instructions on filling out this I2D template and how to get help if you have questions.
+See https://github.com/ampproject/amphtml/blob/main/docs/spec/amp-versioning-policy.md for details on AMP's deprecation policy, instructions on filling out this I2D template and how to get help if you have questions.
 
 If your feature can be removed immediately after deprecation, you can use this issue to track removal as well (changing the title to "Intent-to-Deprecate-and-Remove" and adding the "INTENT TO REMOVE" label).  Otherwise you will file a separate Intent-to-Remove (I2R) issue after the feature has been deprecated and you are ready to remove the feature.
 -->

.github/ISSUE_TEMPLATE/intent-to-remove--i2r-.md

@@ -10,7 +10,7 @@ assignees: ''
 <!--
 Replace/remove all of the text in brackets, including this text.
 
-See https://github.com/ampproject/amphtml/blob/main/spec/amp-versioning-policy.md for details on AMP's deprecation policy, instructions on filling out this I2R template and how to get help if you have questions.
+See https://github.com/ampproject/amphtml/blob/main/docs/spec/amp-versioning-policy.md for details on AMP's deprecation policy, instructions on filling out this I2R template and how to get help if you have questions.
 
 This I2R should be created after your Intent-to-Deprecate (I2D) for the feature was approved.
 -->

3p/README.md

@@ -17,7 +17,7 @@ Examples: Youtube, Vimeo videos; Tweets, Instagrams; comment systems; polls; qui
 -   Avoid client side rendering of iframe content.
 -   If your use of iframes is for style isolation, consider that AMP might provide an iframe-free alternative.
 -   If you can make it not-iframe-based that is much better. (See e.g. the pinterest embed). We will always ask to do this first. E.g. adding a CORS endpoint to your server might make this possible.
--   Must play well within [AMP's sizing framework](https://github.com/ampproject/amphtml/blob/main/spec/amp-html-layout.md).
+-   Must play well within [AMP's sizing framework](https://github.com/ampproject/amphtml/blob/main/docs/spec/amp-html-layout.md).
 -   All JS on container page must be open source and bundled with AMP.
 -   JavaScript loaded into iframe should be reasonable with respect to functionality.
 -   Use the `sandbox` attribute on iframe if possible.
@@ -28,7 +28,7 @@ Examples: Youtube, Vimeo videos; Tweets, Instagrams; comment systems; polls; qui
 
 -   We welcome pull requests by all ad networks for inclusion into AMP.
 -   All ads and all sub resources must be served from HTTPS.
--   Must play well within [AMP's sizing framework](https://github.com/ampproject/amphtml/blob/main/spec/amp-html-layout.md).
+-   Must play well within [AMP's sizing framework](https://github.com/ampproject/amphtml/blob/main/docs/spec/amp-html-layout.md).
 -   For display ads support, always implement amp-ad and instruct your client to use your amp-ad implementation instead of using amp-iframe. Althought amp-iframe will render the ad, ad clicks will break and viewability information is not available.
 -   Providing an optional image only zero-iframe embed is appreciated.
 -   Support viewability and other metrics/instrumentation as supplied by AMP (via postMessage API)

ads/README.md

@@ -89,7 +89,7 @@ The AMP runtime provides the following information to the ad:
     </ul>
   </dd>
   <dt><code>window.context.sourceUrl</code></dt>
-  <dd>Contains the source URL of the original AMP document. See details <a href="../spec/amp-var-substitutions.md#source-url">here</a></code>.</dd>
+  <dd>Contains the source URL of the original AMP document. See details <a href="../docs/spec/amp-var-substitutions.md#source-url">here</a></code>.</dd>
   <dt><code>window.context.startTime</code></dt>
   <dd>Contains the time at which processing of the amp-ad element started.</dd>
 </dl>

ads/google/a4a/docs/Network-Impl-Guide.md

@@ -117,7 +117,7 @@ is allowed by including the following headers in the response:
     custom headers are not included, they will be dropped by the browser.</dd>
 </dl>
 
-For details on CORS verification in AMP context, see [Verify CORS requests](https://github.com/ampproject/amphtml/blob/main/spec/amp-cors-requests.md#verify-cors-header).
+For details on CORS verification in AMP context, see [Verify CORS requests](https://github.com/ampproject/amphtml/blob/main/docs/spec/amp-cors-requests.md#verify-cors-header).
 
 ### Creating an AMPHTML ad extension implementation
 

ads/vendors/custom.md

@@ -222,7 +222,7 @@ If no slot was specified, the server returns a single template rather than an ar
 }
 ```
 
-The ad server must enforce [AMP CORS](https://github.com/ampproject/amphtml/blob/main/spec/amp-cors-requests.md#cors-security-in-amp).
+The ad server must enforce [AMP CORS](https://github.com/ampproject/amphtml/blob/main/docs/spec/amp-cors-requests.md#cors-security-in-amp).
 Here is an example set of the relevant response headers:
 
 ```html

build-system/tasks/check-video-interface-list.js

@@ -19,7 +19,7 @@ const {readFile} = require('fs-extra');
 const {writeDiffOrFail} = require('../common/diff');
 
 /** Checks or updates 3rd party video player list on this Markdown file. */
-const filepath = 'spec/amp-video-interface.md';
+const filepath = 'docs/spec/amp-video-interface.md';
 
 /** Excludes these extensions since they're on a separate list. */
 const excludeGeneric = ['amp-video', 'amp-video-iframe'];

build-system/tasks/create-golden-css/css/main.css

@@ -45,7 +45,7 @@ html.i-amphtml-fie {
 /**
  * Margin:0 is currently needed for iOS viewer embeds.
  * See:
- * https://github.com/ampproject/amphtml/blob/main/spec/amp-html-layout.md
+ * https://github.com/ampproject/amphtml/blob/main/docs/spec/amp-html-layout.md
  */
 body {
   margin: 0 !important;

builtins/amp-img/amp-img.md

@@ -45,7 +45,7 @@ the `layout` attribute.
 [tip type="read-on"]
 
 Learn more about layouts in the
-[AMP HTML Layout System](../../spec/amp-html-layout.md)
+[AMP HTML Layout System](../../docs/spec/amp-html-layout.md)
 spec and
 [Supported Layouts](https://amp.dev/documentation/guides-and-tutorials/develop/style_and_layout/control_layout.html#the-layout-attribute).
 

builtins/amp-pixel/amp-pixel.md

@@ -60,7 +60,7 @@ When processing AMP URLs in the referrer header of analytics requests, strip out
 ### Substitutions
 
 The `amp-pixel` allows all standard URL variable substitutions.
-See the [Substitutions Guide](../../spec/amp-var-substitutions.md) for more information.
+See the [Substitutions Guide](../../docs/spec/amp-var-substitutions.md) for more information.
 
 In the following example, a request might be made to something like `https://foo.com/pixel?0.8390278471201` where the RANDOM value is randomly generated upon each impression.
 

css/ampdoc.css

@@ -44,7 +44,7 @@ html:not([amp4ads]) body {
 /**
  * Margin:0 is currently needed for iOS viewer embeds.
  * See:
- * https://github.com/ampproject/amphtml/blob/main/spec/amp-html-layout.md
+ * https://github.com/ampproject/amphtml/blob/main/docs/spec/amp-html-layout.md
  */
 html:not([amp4ads]) body {
   margin: 0 !important;

docs/building-a-bento-amp-extension.md

@@ -59,7 +59,7 @@ This generates CSS used by the AMP element `<amp-my-element>`, and JSS used by t
 All Bento AMP component extensions have their tag names prefixed with `amp-`.
 Make sure to choose an accurate and clear name for your extension.
 
-Extensions that embed a third-party service must follow the [guidelines for naming a third-party component](../spec/amp-3p-naming.md).
+Extensions that embed a third-party service must follow the [guidelines for naming a third-party component](../docs/spec/amp-3p-naming.md).
 
 ## Directory structure
 
@@ -339,7 +339,7 @@ AmpMyElement['shadowCss'] = CSS;
 ## Actions and events
 
 AMP provides a framework for [elements to fire their own
-events](https://github.com/ampproject/amphtml/blob/main/spec/amp-actions-and-events.md)
+events](https://github.com/ampproject/amphtml/blob/main/docs/spec/amp-actions-and-events.md)
 to allow users of that element to listen and react to the events. For
 example, the `amp-base-carousel` extension fires a `slideChange` event.
 This allow publishers to listen to that event and react to it, for example, by updating an `amp-selector` state to match the current slide shown.
@@ -382,7 +382,7 @@ this.registerApiAction('close', (api) => api.close());
 
 Your element can choose to override the default `activate` method inherited from BaseElement. For example `amp-lightbox` overrides `activate` to define the `open` default case.
 
-You must document your element's actions and events in its own reference documentation and in [`AMP Actions and Events`](https://github.com/ampproject/amphtml/blob/main/spec/amp-actions-and-events.md).
+You must document your element's actions and events in its own reference documentation and in [`AMP Actions and Events`](https://github.com/ampproject/amphtml/blob/main/docs/spec/amp-actions-and-events.md).
 
 ## Allowing proper validation
 
@@ -409,9 +409,9 @@ AMP defines different layouts that elements can choose whether or not to
 support. Your element needs to announce which layouts it supports through
 overriding the `isLayoutSupported(layout)` callback and returning true
 if the element supports that layout. [Read more about AMP Layout
-System](https://github.com/ampproject/amphtml/blob/main/spec/amp-html-layout.md)
+System](https://github.com/ampproject/amphtml/blob/main/docs/spec/amp-html-layout.md)
 and [Layout
-Types](https://github.com/ampproject/amphtml/blob/main/spec/amp-html-layout.md#layout).
+Types](https://github.com/ampproject/amphtml/blob/main/docs/spec/amp-html-layout.md#layout).
 
 ### What layout should your element support?
 

docs/building-an-amp-extension.md

@@ -54,7 +54,7 @@ All AMP extensions (and built-in elements) have their tag names prefixed
 with `amp-`. Make sure to choose an accurate and clear name for your
 extension.
 
-Extensions that embed a third-party service must follow the [guidelines for naming a third-party component](../spec/amp-3p-naming.md).
+Extensions that embed a third-party service must follow the [guidelines for naming a third-party component](../docs/spec/amp-3p-naming.md).
 
 ## Directory structure
 
@@ -183,7 +183,7 @@ AMP.extension('amp-my-element', '0.1', (AMP) => {
     create a lightweight placeholder. This gets called only if the element
     doesn't already have a publisher-provided placeholder (through [the
     placeholder
-    attribute](https://github.com/ampproject/amphtml/blob/main/spec/amp-html-layout.md#placeholder)).
+    attribute](https://github.com/ampproject/amphtml/blob/main/docs/spec/amp-html-layout.md#placeholder)).
 -   **Usage**: Create placeholder DOM and return it. For example,
     amp-instagram uses this to create a placeholder dynamically by creating
     an amp-img placeholder instead of loading the iframe, leaving the iframe
@@ -304,7 +304,7 @@ AMP.extension('amp-carousel', '0.1', (AMP) => {
 ## Actions and events
 
 AMP provides a framework for [elements to fire their own
-events](https://github.com/ampproject/amphtml/blob/main/spec/amp-actions-and-events.md)
+events](https://github.com/ampproject/amphtml/blob/main/docs/spec/amp-actions-and-events.md)
 to allow users of that element to listen and react to the events. For
 example, amp-form extension fires a few events on <form> elements
 like `submit-success`. This allow publishers to listen to that event
@@ -446,7 +446,7 @@ placeholder for itself (in case a placeholder wasn't provided by the
 developer/publisher who is using your element). This allows elements to
 display content as fast as possible and allow prerendering that
 placeholder. Learn [more about placeholder
-elements](https://github.com/ampproject/amphtml/blob/main/spec/amp-html-layout.md#placeholder).
+elements](https://github.com/ampproject/amphtml/blob/main/docs/spec/amp-html-layout.md#placeholder).
 
 NOTE: Make sure not to request external resources in the pre-render
 phase. Requests to the publisher's origin itself are OK. If in doubt,
@@ -599,9 +599,9 @@ AMP defines different layouts that elements can choose whether or not to
 support Your element needs to announce which layouts it supports through
 overriding the `isLayoutSupported(layout)` callback and returning true
 if the element supports that layout. [Read more about AMP Layout
-System](https://github.com/ampproject/amphtml/blob/main/spec/amp-html-layout.md)
+System](https://github.com/ampproject/amphtml/blob/main/docs/spec/amp-html-layout.md)
 and [Layout
-Types](https://github.com/ampproject/amphtml/blob/main/spec/amp-html-layout.md#layout).
+Types](https://github.com/ampproject/amphtml/blob/main/docs/spec/amp-html-layout.md#layout).
 
 ### What layout should your element support?
 

docs/component-validator-rules.md

@@ -276,7 +276,7 @@ tags.
 
 This section adds validation rules for the various layout options available to
 amp tags. See
-[AMP HTML Layout System](https://github.com/ampproject/amphtml/blob/main/spec/amp-html-layout.md)
+[AMP HTML Layout System](https://github.com/ampproject/amphtml/blob/main/docs/spec/amp-html-layout.md)
 to determine which options make sense for your tag.
 
 ### Attribute Validation Options

docs/contributing-code.md

@@ -26,9 +26,9 @@ If your run into any issues finding a Reviewer/Owner or have any other questions
 
 Significant changes (e.g. new components or significant changes to behavior) require consultation with and approval from knowledgeable members of the community.
 
-**If you are making a change to existing behavior, familiarize yourself with AMP's [policy on breaking changes](https://github.com/ampproject/amphtml/blob/main/spec/amp-versioning-policy.md#breaking-changes).**
+**If you are making a change to existing behavior, familiarize yourself with AMP's [policy on breaking changes](https://github.com/ampproject/amphtml/blob/main/docs/spec/amp-versioning-policy.md#breaking-changes).**
 
-**If you are deprecating/removing a feature, follow the [deprecation process](https://github.com/ampproject/amphtml/blob/main/spec/amp-versioning-policy.md#deprecations) instead of this process.**
+**If you are deprecating/removing a feature, follow the [deprecation process](https://github.com/ampproject/amphtml/blob/main/docs/spec/amp-versioning-policy.md#deprecations) instead of this process.**
 
 -   [ ] _Before you start coding_, [find a guide](#find-a-guide) who you can discuss your change with and who can help guide you through the process.
 -   [ ] Agree to the [OpenJSF Contributor License Agreement (CLA)](#contributor-license-agreement).

docs/developing.md

@@ -83,10 +83,10 @@ In particular, we try to maintain "it might not be perfect but isn't broken"-sup
 ## Eng docs
 
 -   [Life of an AMP \*](https://docs.google.com/document/d/1WdNj3qNFDmtI--c2PqyRYrPrxSg2a-93z5iX0SzoQS0/edit#)
--   [AMP Layout system](../spec/amp-html-layout.md)
+-   [AMP Layout system](../docs/spec/amp-html-layout.md)
 -   [Building an AMP Extension](building-an-amp-extension.md)
 
-We also recommend scanning the [spec](../spec/). The non-element part should help understand some of the design aspects.
+We also recommend scanning the [spec](../docs/spec/). The non-element part should help understand some of the design aspects.
 
 ## Builds and releases
 

spec/amp-3p-naming.md → docs/spec/amp-3p-naming.md

@@ -51,4 +51,4 @@ The URL that these components embed is interchangeable, since their src attribut
 
 ### <a id="no-player-suffix"></a> <sup>2</sup> Why is `<amp-youtube>` not suffixed like `<amp-youtube-player>`?
 
-Several media player components names lack the -player prefix, like `<amp-youtube>` and all those the apply in the [video player list](https://github.com/ampproject/amphtml/blob/main/spec/amp-video-interface.md). These were historically created before this guideline.
+Several media player components names lack the -player prefix, like `<amp-youtube>` and all those the apply in the [video player list](https://github.com/ampproject/amphtml/blob/main/docs/spec/amp-video-interface.md). These were historically created before this guideline.

spec/amp-actions-and-events.md → docs/spec/amp-actions-and-events.md

@@ -304,7 +304,7 @@ event.selectedOptions</pre></td>
 
 ### <a name="amp-video-events"></a> amp-video and other Video Elements
 
-The events below are dispatched by `amp-video`, `amp-video-iframe` and [3rd party video players](https://github.com/ampproject/amphtml/blob/main/spec/amp-video-interface.md) like `amp-youtube`.
+The events below are dispatched by `amp-video`, `amp-video-iframe` and [3rd party video players](https://github.com/ampproject/amphtml/blob/main/docs/spec/amp-video-interface.md) like `amp-youtube`.
 
 <table>
   <tr>
@@ -649,7 +649,7 @@ event.response</pre></td>
 
 ### <a name="amp-video-actions"></a> amp-video and other Video Elements
 
-The actions below are supported in `amp-video`, `amp-video-iframe` and [3rd party video players](https://github.com/ampproject/amphtml/blob/main/spec/amp-video-interface.md) like `amp-youtube`.
+The actions below are supported in `amp-video`, `amp-video-iframe` and [3rd party video players](https://github.com/ampproject/amphtml/blob/main/docs/spec/amp-video-interface.md) like `amp-youtube`.
 
 <table>
   <tr>
@@ -712,7 +712,7 @@ actions that apply to the whole document.
   <tr>
     <td><code>navigateTo(url=STRING, target=STRING, opener=BOOLEAN)</code></td>
     <td>
-      <p>Navigates current window to given URL, to the optional specified target if given (currenly only supporting <code>_top</code> and <code>_blank </code>). The optional <code>opener</code> parameter can be specified when using a target of <code>_blank</code> to allow the newly opened page to access <a href="https://developer.mozilla.org/en-US/docs/Web/API/Window/opener"><code>window.opener</code></a>. Supports <a href="https://github.com/ampproject/amphtml/blob/main/spec/amp-var-substitutions.md">standard URL substitutions</a>.</p>
+      <p>Navigates current window to given URL, to the optional specified target if given (currenly only supporting <code>_top</code> and <code>_blank </code>). The optional <code>opener</code> parameter can be specified when using a target of <code>_blank</code> to allow the newly opened page to access <a href="https://developer.mozilla.org/en-US/docs/Web/API/Window/opener"><code>window.opener</code></a>. Supports <a href="https://github.com/ampproject/amphtml/blob/main/docs/spec/amp-var-substitutions.md">standard URL substitutions</a>.</p>
       <p><strong>Caveat:</strong> Using normal <code>&lt;a&gt;</code> links is recommended wherever possible since <code>AMP.navigateTo</code> is not recognized by web crawlers.</p>
     </td>
   </tr>

spec/amp-cache-debugging.md → docs/spec/amp-cache-debugging.md

@@ -41,7 +41,7 @@ If you still have a problem after following these steps, check the table below.
     <tr>
       <td rowspan="2">Assets (e.g., fonts and images) do not appear</td>
       <td>The assets are served with the incorrect MIME type.</td>
-      <td>Specify an <a href="https://github.com/ampproject/amphtml/blob/main/spec/amp-cache-guidelines.md#guidelines-accepted-mime-types">acceptable MIME type</a>.</td>
+      <td>Specify an <a href="https://github.com/ampproject/amphtml/blob/main/docs/spec/amp-cache-guidelines.md#guidelines-accepted-mime-types">acceptable MIME type</a>.</td>
     </tr>
     <tr>
       <td>The AMP Cache cannot access the assets.</td>