pelican學習筆記（二）之Writing content
Writing content
2018/01/25
Articles and pages 文章和頁面
Pelican 認為 “文章(articles)” 是按時間順序排列的內容, 如部落格上的帖子, 因此與日期相關。
“頁面(pages)” 背後的想法是, 它們通常不是時態性質的, 用於不經常更改的內容 (例如, “關於” 或 “聯絡” 頁面)。
你可以在官方庫中找到一些例子在https://github.com/getpelican/pelican/tree/master/samples/content
File metadata 檔案中的資訊
Pelican 儘可能的自己從檔案系統得到資訊（如，關於文章的類別，當不指定時pelican會使用資料夾作為分類依據），但是你仍需要在檔案中提供一些資訊(metadata)。
如果您以 reStructuredText 格式編寫內容, 則可以通過以下語法在文字檔案中提供此資訊 (以 . rst字尾名的檔案):
My super title
#
:date: 2010-10-03 10:20
:modified: 2010-10-04 18:40
:tags: thats, awesome
:category: yeah
:slug: my-super-post
:authors: Alexis Metaireau, Conan Doyle
:summary: Short version for index and feeds
authors 和 tags 可以用分號（;）或逗號 (,) 分隔。
:tags: pelican, publishing tool; pelican, bird
:authors: Metaireau, Alexis; Doyle, Conan
Pelican 通過abbr標記實現了對 reStructuredText 的擴充套件, 以啟用對 HTML 的支援。你可以在你的推送(post)中像這樣寫:
This will be turned into :abbr:
HTML (HyperText Markup Language).
你同樣可以使用 Markdown 語法 （字尾名為 .md
.markdown，.mkd或.mdown）。Markdown生成器要求你先安裝Markdown包，請嘗試執行pip install Markdown命令。
Pelican 同時支援擴充套件的Markdown語法 (Markdown Extensions)，如果擴充套件語法沒有包含在Markdown包中，可能需要另行安裝。
Markdown 的檔案需要像下面一樣新增資訊(metadata)：
Title: My super title
Date: 2010-12-03 10:20
Modified: 2010-12-05 19:30
Category: Python
Tags: pelican, publishing
Slug: my-super-post
Authors: Alexis Metaireau, Conan Doyle
Summary: Short version for index and feeds
This is the content of my super blog post.
其他格式（如 AsciiDoc）需要通過外掛支援，請參與pelican-plugins的相關說明。
Pelican同樣可以處理.html和.htm結尾的HTML檔案。它以非常直接的方式讀取資訊，title從title，body從body：
<html>
<head>
<title>My super title</title>
<meta name="tags" content="thats, awesome" />
<meta name="date" content="2012-07-09 22:28" />
<meta name="modified" content="2012-07-10 20:14" />
<meta name="category" content="yeah" />
<meta name="authors" content="Alexis Métaireau, Conan Doyle" />
<meta name="summary" content="Short version for index and feeds" />
</head>
<body>
This is the content of my super blog post.
</body>
</html>使用 html, 標準資訊有一個簡單的做法: tags可以按Pelican標準要求的通過tags標記指定, 也可以按HTML要求的通過keywords提供資訊。兩者可以互換使用。
請注意, 除了title之外, 本文的其他資訊(metadata)都不是必需提供的: 如果未指定日期, 並且 DEFAULT_DATE 設定為 'fs', 則將依賴於檔案的 “mtime” 時間戳, 並且該類別可以由檔案所在的目錄確定。例如, 位於 python/foobar/myfoobar. rst 的檔案將有一個foobar類別。如果您想以其他方式組織檔案, 而該資料夾的名稱不是一個好的類別名稱, 則可以將設定 USE_FOLDER_AS_CATEGORY 設定為 False。在分析頁面資訊給定的日期時, Pelican支援 W3C’s 建議的ISO 8601。
注意：
在嘗試使用不同的設定 (特別是資訊) 時, 快取可能會發生干擾，使更改可能不可見。在這種情況下, 禁用快取 LOAD_CONTENT_CACHE = False 或使用--ignore-cache命令列開關忽略快取。
modified應是上次更新文章的時間, 如果未指定, 則預設為date。除了可以在模板中顯示modified外, 當您修改文章後將midified設定為當前日期時, feed readers 中的提要條目將自動更新。
authors是一個逗號分隔的文章作者列表。如果只有一個作者可以使用author。
如果你沒有在 post 中指定摘要資訊, 則可以使用 SUMMARY_MAX_LENGTH 設定來指定從文章開頭的多少單詞用作摘要。
還可以通過在 FILENAME_METADATA 設定中設定的正則表示式從檔名中提取資訊。所有匹配的命名組將在資訊物件中設定。FILENAME_METADATA 設定的預設值僅從檔名中提取日期。例如, 如果您想提取日期和slug, 可以設定如下內容:'(?P<date>\d{4}-\d{2}-\d{2})_(?P<slug>.*)'
請注意, 檔案中可用的資訊優先於從檔名中提取的資訊。
2018/01/26
Pages 頁面
如果你在 content 資料夾下建立了一個叫pages的資料夾，所有在這個資料夾內的檔案都會用來生成靜態頁面 ( static pages)，像 About 和 Contact 頁面等。（看下面給出的例子。）
你可以使用設定 DISPLAY_PAGES_ON_MENU 來控制是否所有這些頁面都顯示在主導航選單中。(預設值為 True。)
如果要關閉某個頁面在選單中連結或列出, 請新增status: hidden屬性到其資訊中。這對於製作適合網站主題的錯誤頁面(error pages)非常有用。
Linking to internal content 內部連結
從 Pelican 3.1 開始, 現在可以指定站點內部連結 ( intra-site ) 到源內容層次 (source content hierarchy)結構中的檔案, 而不是生成的層次 (generated hierarchy)結構中的檔案。這使得從當前帖子 ( current post)連結到可能與該帖子並排的其他內容更容易 (而不必確定在站點生成之後其他內容的將放置位置)。
要連結到內部內容 (content目錄中的檔案), 請對連結目標使用以下語法: {filename}path/to/file，注: 正斜線（/）是所有作業系統 (包括 Windows) 的 {filename} 指令中的路徑分隔符。
舉例如下，加入有一個 Pelican 專案的結構像下面這樣：
website/
├── content
│ ├── category/
│ │ └── article1.rst
│ ├── article2.md
│ └── pages
│ └── about.md
└── pelican.conf.py其中article1.rst可能是這樣：
The first article
#################
:date: 2012-12-01 10:02
See below intra-site link examples in reStructuredText format.
`a link relative to the current file <{filename}../article2.md>`_
`a link relative to the content root <{filename}/article2.md>`_article2.md如下：
Title: The second article
Date: 2012-12-01 10:02
See below intra-site link examples in Markdown format.
[a link relative to the current file]({filename}category/article1.rst)
[a link relative to the content root]({filename}/category/article1.rst)Linking to static files 連結到靜態檔案
像上文提到的使用{filename}標識來連線到既非 aritcle 也非 pages 的內容。必須記住, 這些檔案不會被複制到output目錄中, 除非包含它們的源目錄包含在專案的 pelicanconf.py 檔案的 STATIC_PATHS 設定中。Pelican 的配置預設包括images目錄，但必須手動新增其他內容。忘記這樣做會導致連結斷開。
舉例來說，一個專案又如下目錄結構：
content
├── images
│ └── han.jpg
├── pdfs
│ └── menu.pdf
└── pages
└── test.mdtest.md中的連結：
[Our Menu]({filename}/pdfs/menu.pdf)pelicanconf.py檔案設定如下：
STATIC_PATHS = ['images', 'pdfs']網站生成的時候就會複製han.jpg到output/image/han.jpg，menu.pdf到output/pdfs/menu.pdf，並且新增正確的連結到test.md。
Mixed content in the same directory 同一資料夾下的混合內容
從 Pelican 3.5 開始, 靜態檔案可以安全地與頁面原始檔共享源目錄, 而不會在生成的站點中公開頁面源。任何此類目錄都必須同時新增到 STATIC_PATHS 和 PAGE_PATHS (或 STATIC_PATHS 和 ARTICLE_PATHS)。Pelican 通常會識別和處理頁面原始檔, 並將其餘的檔案複製到為靜態檔案保留的單獨目錄中。
Note: 將靜態和內容原始檔放在同一個源目錄中並不能保證它們最終會在生成的站點中的同一位置。為確保如此的最簡單方法是使用 {attach} 連結語法 (參見下一節)。或者, 可以將 STATIC_SAVE_AS、PAGE_SAVE_AS 和 ARTICLE_SAVE_AS 屬性 (以及相應的 * _URL 屬性) 設定為將不同型別的檔案放在一起, 就像在早期版本的 Pelican 中一樣。
Attaching static files 附件
從 Pelican 3.5 開始, 靜態檔案(static files)可以使用{attach}path/to/file將目標 “附加” 到一個網頁或文章上，這類似於 {filename} 語法, 但也將靜態檔案重新定位到連結文件的output目錄中。如果靜態檔案源自連結文件源下的子目錄, 則該關係將保留在輸出上。否則, 它將成為連結文件的同級。
這隻適用於連結到靜態檔案, 而且僅當它們源自於 STATIC_PATHS 屬性中包含的目錄時。
舉個栗子，如下的目錄結構：
content
├── blog
│ ├── icons
│ │ └── icon.png
│ ├── photo.jpg
│ └── testpost.md
└── downloads
└── archive.zippelicanconf.py設定如下：
PATH = 'content'
STATIC_PATHS = ['blog', 'downloads']
ARTICLE_PATHS = ['blog']
ARTICLE_SAVE_AS = '{date:%Y}/{slug}.html'
ARTICLE_URL = '{date:%Y}/{slug}.html'testpost.md內容如下：
Title: Test Post
Category: test
Date: 2014-10-31
[Downloadable File]({attach}/downloads/archive.zip)生成器生成的output目錄結構如下：
output
└── 2014
├── archive.zip
├── icons
│ └── icon.png
├── photo.jpg
└── test-post.html請注意, 所有使用 {attach} 連結的檔案最終都在文章的輸出目錄中或下面。
如果靜態檔案 ( static file )被多次連結, 則 {attach} 的重新定位功能將只在要處理的第一個連結中起作用。在第一個連結之後, Pelican將像 {filename} 一樣處理 {attach}。這樣可避免中斷已處理的連結。
從多個文件連結到檔案時要小心： 由於 Pelican 沒有定義處理文件的順序，第一個指向檔案的連結確定了其最終位置，因此在由多個文件連結的檔案上使用 {attach}時會導致在不同的版本生成時檔案位置發生更改（ cause its location to change from one site build to the next）。(這是否在實際中發生受作業系統、檔案系統、Pelican 版本以及從專案中新增、修改或刪除的文件的影響。）任何連結到檔案舊位置的外部站點都可能會發現它們的連結已失效。因此, 僅當在連結的文件在同一個目錄下時，才建議使{attach}，並且要同時全部使用{attach}。It is therefore advisable to use {attach} only if you use it in all links to a file, and only if the linking documents share a single directory. 在這樣的情況下, 檔案的輸出位置在將來的生成中不會更改。在無法採取這些預防措施的情況下, 請考慮使用 {filename} 連結而不是 {attach} , 並讓該檔案的位置由專案的 STATIC_SAVE_AS 和 STATIC_URL 設定確定。(每個檔案 save_as 和 url 仍然可以在 EXTRA_PATH_METADATA 中設定重寫。) 此段落翻譯不好，大家將就看下
你可以使用{author}name連線到作者；{category}foobar連線到類別；{index}到索引；{tag}tagname到標籤。
Deprecated internal link syntax 快要過時的內部連結語法
為了與早期版本保持相容, Pelican 仍然支援垂直條 (| |)的內部連結。例如: | filename | an_article.rst， | tag | tagname |， |category | foobar。語法從 | |到 {} 的改變是為了避免與擴充套件 Markdown 或 reST 的指令衝突。可能最終會刪除對舊語法的支援。
Importing an existing site 從已存在的站點匯入
可以用一個簡單的指令碼實現從 WordPress、Tumblr、Dotclear 和Rss feeds的匯入，詳見站點匯入
Translations 翻譯
提供多語種的文章是可行的，為了做到這些，你需要在文章或是頁面中新增lang資訊，並設定DEFAULT_LANG屬性（預設英語[en])。有了這些設定, 將只列出具有預設語言的文章, 並且每篇文章都附有該文章的可用翻譯列表。
Note：
Pelican 的核心功能不建立每個語言的翻譯模板的子站點 (例如 example.com/de)。對於這樣的高階功能, 可以使用 i18n_subsites 外掛。
Pelican 使用文章的 URL “slug” 來確定兩個或更多的文章是否是互相的翻譯。可以在檔案的資訊(metadata)中手動設定slug;如果沒有明確設定, Pelican 將通過標題自動生成slug。
下面給個例子，這裡有兩篇文章，一個英語一個法語。
英語文章：
Foobar is not dead
##################
:slug: foobar-is-not-dead
:lang: en
That's true, foobar is still alive!法語版：
Foobar n'est pas mort !
#######################
:slug: foobar-is-not-dead
:lang: fr
Oui oui, foobar est toujours vivant !釋出內容後, 您可以看到這兩篇文章中唯一的共同點就是slug, 它在這裡是一個識別符號。如果您不希望以這種方式顯式定義該slug, 則必須確保翻譯的文章標題相同, 因為將從文章標題自動生成slug。
如果不希望 DEFAULT_LANG 檢測到某個特定文章的原始版本, 請在資訊（metadata）中使用translation指定哪些帖子是翻譯的版本：
Foobar is not dead
##################
:slug: foobar-is-not-dead
:lang: en
:translation: true
That's true, foobar is still alive!Syntax highlighting 語法高亮
Pelican 可以為您的程式碼塊提供彩色的語法高亮。為此, 您必須在內容檔案中使用以下約定。
對於 reStructuredText, 請使用code-block指定要突出顯示的程式碼型別 (在此示例中, 我們將使用 python)：
.. code-block:: python
print("Pelican is a static site generator.")對於使用 CodeHilite 擴充套件來提供語法高亮的Markdown, 請在程式碼塊的正上方包含語言識別符號, 同時縮排識別符號和程式碼：
There are two ways to specify the identifier:
:::python
print("The triple-colon syntax will *not* show line numbers.")
To display line numbers, use a path-less shebang instead of colons:
#!python
print("The path-less shebang syntax *will* show line numbers.")使用 reStructuredText 時, 程式碼塊指令 (code-block directive) 中提供了以下選項:
| 選項 | 有效值 | 描述 |
|---|---|---|
| anchorlinenos | N/A | 如果在<a>標記中顯示行號 |
| classprefix | String | 標記類名 |
| hl_lines | numbers | 要突出顯示的行的list, 其中要突出顯示的行號由空格分隔。這類似於在Sphinx中的emphasize-lines, 但它不支援用連字元分隔的行號範圍, 或逗號分隔的行號。 |
| lineanchors | string | 在lineanchors和-linenumber之間對其中的每一行進行包裝。 |
Note：不同的版本中, 您的 Pygments 模組可能沒有所有可用的選項。有關每個選項的詳細資訊, 請參閱 Pygments 文件的 HtmlFormatter 部分。
例如, 下面的程式碼塊啟用行號, 從153開始, 並使用 pgcss 字首 Pygments css 類, 以使名稱更加獨特, 並避免可能的 css 衝突:
.. code-block:: identifier
:classprefix: pgcss
:linenos: table
:linenostart: 153
<indented code block goes here>Publishing drafts 草稿
如果要將文章釋出為草稿 (例如, 在釋出前供好友審閱)，可以將Status:draft 屬性新增到其資訊（metadata) 中。然後, 該文章將輸出到 draft 資料夾, 而不在索引頁上或任何類別或標記頁上列出。
如果您想要所有文章自動作為草稿釋出 (在文章完成前不會意外地釋出), 請在 DEFAULT_METADATA 中包括以下狀態:
DEFAULT_METADATA = {
'status': 'draft',
}若要在以上情況，即設定了預設狀態為 “草稿” 時釋出帖子, 請更新帖子的資訊以包括Status: published。
學習小結
由於對rst格式並不熟悉，重點還是看了看怎麼使用目錄結構以及markdown。
文章中應該包括的資訊有：
| 標記 | 內容 |
|---|---|
| Title | 標題 |
| Date | yyyy-mm-dd hh:mm |
| Modified | 修改時間，格式同上 |
| Tags | 標籤 |
| Slug | Slug用來指定檔名 |
| Authors / Author | 作者，作者 |
| Summary | 概要 |
連結是個重要的東西，會影響build以後的目錄結構。讓我欣喜的是居然還能夠提供附件，這個比我預期要好很多。
多篇文章指向同一個檔案那裡沒有看懂怎麼回事，只能待將來實操多實驗幾次來總結了。