格式指南與教學
指南與教學以 Markdown 格式提交,並具有額外的 frontmatter (前言) 和 shortcode (短代碼) 格式。
文件位置
amp.dev 上的內容來自兩個儲存庫:amp.dev 和 AMPHTML。元件下的所有參考文件都來自 AMPHTML,無論是內建元件還是擴充功能。
還有其他一些文件從 AMPHTML 匯入到 amp.dev。它們在此檔案中列出。請勿在 amp.dev 儲存庫中更新這些文件 – 您的變更將在後續建置中被覆寫!
Frontmatter (前言)
Frontmatter (前言) 位於每個指南和教學的頂部。
範例
$title: Include Custom JavaScript in AMP Pages
$order: 7
formats:
- websites
author: CrystalOnScript
contributors:
- fstanis
description: For web experiences requiring a high amount of customization AMP has created amp-script, a component that allows the use of arbitrary JavaScript on your AMP page without affecting the page's overall performance.
$title | 文件的標題,將顯示在目錄中。第一個單字的第一個字母請大寫,但 "AMP" 和其他專有名詞除外。請使用 & 符號 `&` 而非文字 `and`。 |
$order | 定義文件在目錄中出現的位置。您可能需要編輯其他文件中的 `$order`,使其出現在正確的位置。 |
formats | 列出您的文件相關的 AMP 體驗。如果您的文件與 AMP 網站和 AMP 故事相關,但與 AMP 廣告或 AMP 電子郵件無關,您的 frontmatter (前言) 看起來會像這樣: ```yaml formats: - websites - stories ``` |
author | 作者就是您!請使用您的 GitHub 使用者名稱。 |
contributors | 列出任何對您的文件做出貢獻的人員。此欄位為選填。 |
description | 撰寫您的指南或教學的簡短描述。這有助於搜尋引擎最佳化,讓您的作品能送到需要它的人手中! |
tutorial | 在 frontmatter (前言) 中新增 `tutorial: true`,讓網站在教學旁邊新增教學圖示。教學位於目錄中其區段的底部。 |
Shortcodes (短代碼)
如需短代碼及其用途的清單,請參閱 GitHub 上的 documentation.md。
圖片
amp.dev 是用 AMP 建構的!因此,我們的圖片必須符合 amp-img
標準。建置過程使用以下語法將圖片轉換為正確的 amp-img
格式。
{{ image('/static/img/docs/tutorials/custom-javascript-tutorial/image1.jpg', 500, 369, layout='intrinsic', alt='Image of basic amp script tutorial starter app') }}
篩選區段
有些文件可能與多種 AMP 格式相關,但某些格式可能需要進一步的說明或資訊,而這些資訊與其他格式無關。您可以將這些區段包裝在以下短代碼中來篩選它們。
[filter formats="websites"] This is only visible for [websites](?format=websites). [/filter] [filter formats="websites"] This is only visible for [websites](?format=websites). [/filter] [filter formats="websites, email"] This is visible for [websites](?format=websites) & [email](?format=email). [/filter] [filter formats="stories"] This is visible for [stories](?format=stories). [/filter]
提示
您可以透過將文字包裝在以下短代碼中來新增提示和重點提示
[tip type="default"] Default tip [/tip] [tip type="important"] Important [/tip] [tip type="note"] Note [/tip] [tip type="read-on"] Read-on [/tip]
程式碼片段
將程式碼片段放在三組反引號內,並在第一組反引號的末尾指定語言。
```html // code sample ``` ```css // code sample ``` ```js // code sample ```
如果您的程式碼包含雙大括號,如果您使用 amp-mustache
樣板,通常會是這種情況,您必須包裝程式碼部分
```html {% raw %} // code with double curly braces {% endraw %} ```
清單中的程式碼片段
Python-Markdown 有一些限制。在清單中包含程式碼片段時,請使用以下語法
1. First: [sourcecode:html] <html> <p>Indented content.</p> </html> [/sourcecode] 2. Second 3. Third
預覽程式碼範例
程式碼範例可以具有預覽和/或連結到 AMP Playground 版本。
[example preview="default: none|inline|top-frame" playground="default: true|false" imports="<custom-element-1>,<custom-element-2>,..." template="<custom-template>"] ```html // code sample ``` [/example]
使用 preview
屬性來定義預覽的產生方式
-
none:不會產生預覽
-
inline:範例預覽顯示在原始程式碼上方。只有在程式碼不包含任何
head
元素的情況下,內嵌預覽才適用於一般網站範例。對於不需要任何樣式或其他head
元素的小範例,請使用此選項 (匯入不算在內,因為它們是透過imports
屬性指定的)。 -
top-frame:範例預覽顯示在 iframe 內的原始程式碼上方。方向可以在
portrait
(直向) 和landscape
(橫向) 模式之間切換。您可以透過指定額外屬性來預先選取方向 -
orientation:
default: landscape|portrait
如果需要自訂元素,請在 imports
屬性中指定它們,以逗號分隔的清單,元件名稱後接冒號和版本。如果您的程式碼使用 amp-mustache
,請改為在 template
屬性中指定相依性。
對於包含資源連結的電子郵件內容,請在原始碼中使用預留位置 {{server_for_email}}
。
Inline Sample (內嵌範例)
這是一個簡單的內嵌範例嵌入。您可以透過內嵌樣式定義 CSS
[example preview="inline" playground="true"] ```html <div style="background: red; width: 200px; height: 200px;">Hello World</div> ``` [/example] [/example]
這就是它的樣子
<div style="background: red; width: 200px; height: 200px;">Hello World</div>
amp-consent
),可能會導致衝突。Top-Frame Preview (頂層框架預覽)
每當您需要指定標頭元素或在 <style amp-custom>
內定義全域樣式時,請使用頂層框架預覽。
[example preview="top-frame" playground="true"] ```html <head> <script async custom-element="amp-youtube" src="https://cdn.ampproject.org/v0/amp-youtube-0.1.js"></script> <style amp-custom> body { background: red; } </style> </head> <body> <h1>Hello AMP</h1> <amp-youtube width="480" height="270" layout="responsive" data-videoid="lBTCB7yLs8Y"> </amp-youtube> </body> ``` [/example]
這就是它的樣子
<head>
<script async custom-element="amp-youtube" src="https://cdn.ampproject.org/v0/amp-youtube-0.1.js"></script>
<style amp-custom>
body {
background: red;
}
</style>
</head>
<body>
<h1>Hello AMP</h1>
<amp-youtube width="480"
height="270"
layout="responsive"
data-videoid="lBTCB7yLs8Y">
</amp-youtube>
</body>
AMP Stories (AMP 故事)
針對預覽 AMP 故事,將 preview="top-frame"
與 orientation="portrait"
一起使用。
[example preview="top-frame" orientation="portrait" playground="true"] ```html <head> <script async custom-element="amp-story" src="https://cdn.ampproject.org/v0/amp-story-1.0.js"></script> <style amp-custom> body { font-family: 'Roboto', sans-serif; } amp-story-page { background: white; } </style> </head> <body> <amp-story standalone> <amp-story-page id="cover"> <amp-story-grid-layer template="vertical"> <h1>Hello World</h1> <p>This is the cover page of this story.</p> </amp-story-grid-layer> </amp-story-page> <amp-story-page id="page-1"> <amp-story-grid-layer template="vertical"> <h1>First Page</h1> <p>This is the first page of this story.</p> </amp-story-grid-layer> </amp-story-page> </amp-story> </body> ``` [/example]
這就是它的樣子
<head>
<script async custom-element="amp-story"
src="https://cdn.ampproject.org/v0/amp-story-1.0.js"></script>
<style amp-custom>
body {
font-family: 'Roboto', sans-serif;
}
amp-story-page {
background: white;
}
</style>
</head>
<body>
<amp-story standalone>
<amp-story-page id="cover">
<amp-story-grid-layer template="vertical">
<h1>Hello World</h1>
<p>This is the cover page of this story.</p>
</amp-story-grid-layer>
</amp-story-page>
<amp-story-page id="page-1">
<amp-story-grid-layer template="vertical">
<h1>First Page</h1>
<p>This is the first page of this story.</p>
</amp-story-grid-layer>
</amp-story-page>
</amp-story>
</body>
AMP Email (AMP 電子郵件) 的絕對 URL
請注意,如果嵌入在 AMP 電子郵件中,我們如何使用 {{server_for_email}}
使端點 URL 成為絕對 URL。
[example preview="top-frame" playground="true"] ```html <div class="resp-img"> <amp-img alt="flowers" src="{{server_for_email}}/static/inline-examples/images/flowers.jpg" layout="responsive" width="640" height="427"></amp-img> </div> ``` [/example]
這就是它的樣子
<div class="resp-img">
<amp-img alt="flowers"
src="/static/inline-examples/images/flowers.jpg"
layout="responsive"
width="640"
height="427"></amp-img>
</div>
跳脫 Mustache 樣板
這是一個使用遠端端點的 top-frame
範例。必須使用 {% raw %}
和 {% endraw %}
在範例中跳脫 Mustache 樣板
[example preview="top-frame" playground="true" imports="amp-list:0.1" template="amp-mustache:0.2"] ```html <amp-list width="auto" height="100" layout="fixed-height" src="{{server_for_email}}/static/inline-examples/data/amp-list-urls.json"> <template type="amp-mustache">{% raw %} <div class="url-entry"> <a href="{{url}}">{{title}}</a> </div> {% endraw %} </template> </amp-list> ``` [/example]
這就是它的樣子
<amp-list width="auto" height="100" layout="fixed-height"
src="/static/inline-examples/data/amp-list-urls.json">
<template type="amp-mustache">
<div class="url-entry">
<a href="{{url}}">{{title}}</a>
</div>
</template>
</amp-list>
連結
您可以使用標準 Markdown 連結語法連結到其他頁面
[link](../../../courses/beginning-course/index.md)
當連結到 amp.dev 上的另一個頁面時,參考將是目標檔案的相對檔案路徑。
錨點
使用錨點連結到文件中的特定區段
[link to example section](#example-section)
在連結到沒有錨點的區段之前,請使用 <a name="#anchor-name></a>
建立錨點目標。一個好的位置是在區段標題的末尾
## Example section <a name="example-section"></a>
您只能在錨點中使用字母、數字、破折號和底線。請使用與標題相符或描述區段的簡短英文錨點名稱。確保錨點名稱在文件中是唯一的。
當翻譯頁面時,錨點名稱不得變更,並且必須保留英文。
當您建立將從另一個頁面連結使用的錨點時,您也應該在所有翻譯中建立相同的錨點。
AMP 格式篩選器
元件文件、指南和教學以及範例可以依 AMP 格式篩選,例如 AMP 網站或 AMP 故事。當連結到此類頁面時,您應該明確指定目標支援的格式,方法是在連結中附加格式參數
[link](../../learn/amp-actions-and-events.md?format=websites)
只有當您確定目標支援您的頁面支援的所有格式時,才能省略參數。
元件參考
如果您的連結省略版本部分,則元件參考文件的連結將自動指向最新版本。當您明確想要指向特定版本時,請指定完整名稱
[latest version](../../../components/reference/amp-carousel.md?format=websites)
[explicit version](../../../components/reference/amp-carousel-v0.2.md?format=websites)
文件結構
標題、章節標題和小標題
標題、章節標題和小標題中,第一個單字的第一個字母大寫,其餘為小寫。例外情況包括 AMP 和其他專有名詞。沒有標題命名為 Introduction
(簡介),簡介在文件標題之後。
文件命名
使用破折號命名慣例命名文件。
正確 | 錯誤 |
hello-world-tutorial.md | hello_world_tutorial.md |
website-fundamentals.md | websiteFundamentals.md |
actions-and-events.md | actionsandevents.md |
-
由 @CrystalOnScript 撰寫