INTRODUCTION TO ATOM

###### tags: `-ing` `toys` # INTRODUCTION TO ATOM https://validator.w3.org/feed/docs/atom.html ## What is Atom? Atom 是 XML-based 的 Web 內容和 metadata 聯合格式的名稱，是用於發布和編輯屬於定期更新網站的 Web 資源的應用程序級協議。所有的 Atom feeds 必須是格式良好的 [XML](http://www.w3.org/TR/REC-xml) 文檔，且 media type (媒體類型) 標識為 `application/atom+xml` 。 ### 關於這個文件本文檔重點介紹 [IETF](http://www.ietf.org/) [AtomPub](http://www.ietf.org/html.charters/atompub-charter.html) 工作組製作的 [Atom Syndication 格式](https://validator.w3.org/feed/docs/rfc4287.html)。如果本文檔與 Internet 草案不同，則 Internet 草案將被視為權威性的。一般考慮： - 本文檔中描述的所有元素必須位於 http://www.w3.org/2005/Atom 命名空間中。 - Atom 中的所有時間戳必須符合 [RFC 3339](http://www.faqs.org/rfcs/rfc3339.html)。 - 除非另外指定，否則所有值必須是純文本（即，沒有實體編碼的 html ）。 - [`xml：lang`](http://www.w3.org/TR/REC-xml/#sec-lang-tag) 可以用來識別任何人類可讀文本的語言。 - [`xml：base`](http://www.w3.org/TR/xmlbase/) 可以用來控制相對 URI 的解析方式。 ## Sample feed ```atom <?xml version="1.0" encoding="utf-8"?> <feed xmlns="http://www.w3.org/2005/Atom"> <title>Example Feed</title> <link href="http://example.org/"/> <updated>2003-12-13T18:30:02Z</updated> <author> <name>John Doe</name> </author> <id>urn:uuid:60a76c80-d399-11d9-b93C-0003939e0af6</id> <entry> <title>Atom-Powered Robots Run Amok</title> <link href="http://example.org/2003/12/13/atom03"/> <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id> <updated>2003-12-13T18:30:02Z</updated> <summary>Some text.</summary> </entry> </feed> ``` ## `<feed>` 的元素一個 Feed 包含一些 metadata，後面是任意數量的條目。 ### 必要的 `<feed>` 元素 / Required feed elements - **`<id>`**：用一個獨有且永久的 URI 識別一個 feed。若你有一個長期、可續租的域名，你可以隨意使用你的網址 ```atom <id>http://example.com/</id> ``` - **`<title>`**：給 Feed 包含一個「人可識別」的標題，通常和網站標題相同，這個值不應該空白。 ```atom <title>Example, Inc.</title> ``` - **`<updated>`**：Feed 最後一次更動時間 ```atom <updated>2003-12-13T18:30:02Z</updated> ``` ### 建議使用的 `<feed>` 元素 / Recommended feed elements - **`<author>`**：給這個 Feed 命名一個作者。一個 Feed 可能有很多個 `<author>` 元素。 ```atom <author> <name>John Doe</name> <email>JohnDoe@example.com</email> <uri>http://example.com/~johndoe</uri> </author> ``` 一個 Feed 必須包含至少一個 `<author>` 元素，除非全部的 `<entry>` 元素都有最少一個 `<author>`。 - **`<link>`**：識別一個相關的網頁。關聯的 `type` 是由 `rel` 屬性定義。一個 Feed 僅限一個 `alternate`，對每個 `type` 和 `hreflang`。 (A feed is limited to one alternate per type and hreflang. ) 一個 Feed 應該包含一個退回連結到這個 Feed 自身。 ```atom <link rel="self" href="/feed" /> ``` ### 選用的 `<feed>` 元素 / Optional feed elements - **`<category>`**：一個 `<feed>` 所屬的特定一個類別。一個 `<feed>` 可能有多個類別元素。 ```atom <category term="sports"/> ``` - **`<contributor>`**：命名一個貢獻者的資料，可能有多個貢獻者 ```atom <contributor> <name>Jane Doe</name> </contributor> ``` - **`<generator>`**：識別一個用來生成 `<feed>` 的軟體，用來除錯或用於其他的目的。兩個屬性 `uri` 和 `version` 都是選用。 ```atom <generator uri="/myblog.php" version="1.0"> Example Toolkit </generator> ``` - **`<icon>`**：一個小圖做識別，他提供 `<feed>` 一個標誌性的視覺識別，應該是方形的圖片。 ```atom <icon>/icon.jpg</icon> ``` - **`<logo>`**：一個大的影像做識別，他提供 `<feed>` 視覺的辨識。影像寬應該是高的兩倍。 ```atom <logo>/logo.jpg</logo> ``` - **`<rights>`**：傳達關於版權的資訊 e.g. copyrights, 在 `<feed>` 之中或之外。 ```atom <rights> © 2005 John Doe </rights> ``` - **`<subtitle>`**：為這個 Feed 包含一個人可是別的描述或子標題。 ```atom <subtitle>all your examples are belong to us</subtitle> ``` ## Elements of `<entry>` 的元素一個 `<entry>` 的範例，是一個 weblog 的單個貼文。 ### Required Elements of `<entry>` 必要的元素 - **`<id>`**：用一個獨有且永久的 URI 識別一個 feed。關於如何做一個好的id的建議可以在這裡找到。兩個 entries 的 id 在一個 Feed 裡可以有相同值，如果它們代表相同的條目在不同的時機。 ```atom <id>http://example.com/blog/1234</id> ``` - **`<title>`**：給此條目一個人類可辨識的標題。這個值不該被留白。 ```atom <title>Atom-Powered Robots Run Amok</title> ``` - **`<updated>`**：最後一次這個條目被定義的時間。更正一個錯字時，這個值不用改變。只有重大的修改，通常，Feed中的不同條目將具有不同的更新時間戳。 ```atom <updated>2003-12-13T18:30:02-05:00</updated> ``` ### Recommended elements of `<entry>` 建議的元素 - **`<author>`**：為條目命名一個作者。一個條目可能有多個作者。一個條目必須包含至少一個 author 元素，除非在封閉的 Feed 中有一個 author 元素，或者在封閉的 source 元素中有一個 author 元素。 ```atom <author> <name>John Doe</name> </author> ``` - **`<content>`**：包含或鏈接到的條目的完整內容。如果沒有 alternate (備用) 鏈接，則必須提供 content，如果沒有 summary，應提供 content。 ```atom <content>complete story here</content> ``` - **`<link>`**：識別一個相關的網頁。關聯的 "type" 是由 `rel` 屬性定義。一個 Feed 僅限於一個 `alternate` (替代) ，每個 type 和 hreflang。一個 entry 必須包含一個 `alternate` link 若沒有 `content` 元素。 ```atom <link rel="alternate" href="/blog/1234"/> ``` - **`<summary>`**：傳達一個簡短的摘要，摘要或摘錄的條目。如果沒有為條目提供 content，或者內容不是內聯（即，包含 src 屬性），或者內容是使用 base64 編碼的，則應提供摘要。更多信息在這裡。 ```atom <summary>Some text.</summary> ``` ### Optional elements of `<entry>` 選用的元素 - **`<category>`**：指定 `<entry>` 所屬的類別。一個條目可能有多個類別元素。 ```atom <category term="technology"/> ``` - **`<contributor>`**：為 `<entry>` 命名一個貢獻者。可能有多個貢獻者。 ```atom <contributor> <name>Jane Doe</name> </contributor> ``` - **`<published>`**：包含 `<entry>` 初始創建或條目的第一個可用的時間。 ```atom <published>2003-12-13T09:17:51-08:00</published> ``` - **`<rights>`**：傳達有關權利的信息，例如版權，在入場和結束。 ```atom <rights type="html"> &copy; 2005 John Doe </rights> ``` - **`<source>`**：若這是一個副本，包含來源 Feed 的 metadata。 ```atom <source> <id>http://example.org/</id> <title>Example, Inc.</title> <updated>2003-12-13T18:30:02Z</updated> </source> ``` ## 常見結構 / Common Constructs ### 類別 / Category `<category>` 有一個必須的屬性 `term` (術語)，和兩個選用的屬性 `scheme`、`label` `term` 識別 category (類別) `scheme` 會透過一個 URI 識別分類格式 `label` 提供顯示一個人類可識別的標籤 ### 內容 / Content `<content>` 無論包含了或鏈接到，`<entry>` 的完整內容。最常見的案例，該 `type` 屬性為 `text`，`html`，`xhtml`，在這種情況下，內容元素定義為與其他的文本結構相同。否則，如果 `src` 屬性存在，代表可以找到內容的 URI；若存在 `type` 屬性，則代表內容的媒體類型。否則，若 `type` 屬性結束在 `+xml` 或 `/xml`，則這個類型的 `xml` 文件會包含在 inline。否則，若 `type` 屬性始於 `text`，則這個類型的跳脫文件會包含在 inline。否則，一個指定媒體類型的 base64 編碼的文件包含在 inline。 ### 連結 / Link `<link>` 是在HTML 的鏈接元素之後的一個格式。它有一個必需的屬性，`href`；和五個可選屬性：`rel`，`type`，`hreflang`，`title`，和 `length`。 - `href` 是 URI 引用的資源（通常是 Web 頁面） - `rel` 包含一個單一連結關係 type。它可以是一個完整的 URI（參見伸長），或下面的一個預定義值（缺省值= `alternate` )： - `alternate`：一個 entry 或 feed 的備用表示，舉例說 entry 的 html 版本的永久連結，或 weblog 的首頁。 - `enclosure`：一個相關的資源，其尺寸可能很大，並且可能需要特殊處理，例如音頻或視頻錄製。 - `related`：一個文件，關聯到 entry 或 feed。 - `self`：Feed 本身。 - `via`：在 entry 中提供的信息的來源。 - `type`：在 resource 指示的媒體類型。 - `hreflang`：引用資源的指示語言。 - `title`：人類可識別關於 link 的訊息，通常用於顯示目的。 - `length`：資源的長度，以字節為單位。 ### 人類 / Person `<author>` 和 `<contributor>` 形容一個人，公司或類似機構。它有一個必需的元素，`<name>` 和兩個可選元素：`<uri>`、`<email>`。 `<name>`：該主人人類可讀名稱。 `<uri>`：該主人網站主頁。 `<email>`：該主人電子郵件地址。 ### 文本 / Text `<title>`, `<summary>`, `<content>` 和 `<rights>` 包含人類可識別的文字，通常在小份量中。`type` 屬性確定這個資訊是如何編碼的 (`default="text"`) 若 `type ="text"`，那麼這個元素包含純文本，沒有實體轉義的 HTML。 ```atom <title type="text">AT&T bought by SBC!</title> ``` 若 `type="html"`, 那麼這個元素包含實體轉義的 HTML。 ```atom <title type="html"> AT&amp;T bought &lt;b&gt;by SBC&lt;/b&gt;! </title> ``` 若 `type="xhtml"` 則這個元素包含 inline XHTML，包裹在一個 div 元素。 ```atom <title type="xhtml"> <div xmlns="http://www.w3.org/1999/xhtml"> AT&T bought <b>by SBC</b>! </div> </title> ``` ## 擴展 Atom / Extending Atom atom 內容元素被設計為支持直接包含其他 XML 詞彙表。任何完全限定的 URI 都可以用作鏈接元素的 rel 屬性的值。來自其他命名空間的元素幾乎可以包含在任何地方。這意味著大多數 RSS 1.0 和 RSS 2.0 模塊都可以在 Atom 中使用。 ## See Also ...略

Syntax	Example	Reference
# Header	Header	基本排版
- Unordered List	Unordered List
1. Ordered List	Ordered List
- [ ] Todo List	Todo List
> Blockquote	Blockquote
Bold font	Bold font
Italics font	Italics font
~~Strikethrough~~	~~Strikethrough~~
19^th^	19^th
H~2~O	H₂O
++Inserted text++	Inserted text
==Marked text==	Marked text
[link text](https:// "title")	Link
![image alt](https:// "title")	Image
`Code`	`Code`	在筆記中貼入程式碼
```javascript var i = 0; ```	`var i = 0;`
:smile:		Emoji list
{%youtube youtube_id %}	Externals
$L^aT_eX$	L^aT_eX
:::info This is a alert area. :::	This is a alert area.