pelican 使用教學

pelican 預設支援 reStructuredText 格式，並可透過 python 之 Markdown 模組以支援 Markdown 語法。

必須注意的是，無論是 reStructuredText 或 Markdown，其語法支援程度將隨 pelican 佈景主題而異。例如多數的 pelican theme 均無實作 reStructuredText 之 image :scale: （調整圖片大小）屬性。

1. pelican 網站目錄結構

使用 pelican-quickstart 建立網站後，目錄結構如下：

yourproject/
├── content
│   └── (pages)
├── output
├── develop_server.sh
├── Makefile
├── pelicanconf.py       # Main settings file
└── publishconf.py       # Settings to use when ready to publish

./content/: 您可以將 reStructuredText 或 Markdown 格式的文章放置於此目錄下。若您需要建立分類，只要在此目錄下再建立子目錄即可。
./output/: html 輸出位置。因為 pelican 僅產生靜態網頁，您只要將網頁伺服器的目錄指定於此，即可對外提供網站服務。
pelicanconf.py: pelican 網站基本設定。可在此設定作者、佈景主題、網頁連結、外掛參數等。

2. 使用 reStructuredText 撰寫

reStructuredText 是 python 界首推的排版格式。支援的格式屬性較 Markdown 多出許多。網路上關於 reStructuredText 的語法介紹網站很多，在此便不贅述。推薦可以參考這個網站。

一個典型的 reStructuredText pelican 文章如下：

My super title
##############

:date: 2010-10-03 10:20
:tags: thats, awesome
:category: yeah
:slug: my-super-post
:author: Alexis Metaireau
:summary: Short version for index and feeds

This is the content of my super blog post.

其中，最上方的 title 是必備的，其他則可以選填。

若您需要自訂本頁網址，可使用 :slug: 定義。

3. 使用 Markdown 撰寫

Markdown 是近年竄起的排版格式，其語法簡潔，易懂易學，是許多程式開發者撰寫文件時的首選。同樣的網路上也有很多 Markdown 教學，個人推薦這篇教學。

一個典型的 Markdown pelican 文章如下：

Title: My super title
Date: 2010-12-03 10:20
Category: Python
Tags: pelican, publishing
Slug: my-super-post
Author: Alexis Metaireau
Summary: Short version for index and feeds

This is the content of my super blog post.

其中，最上方的 Title 是必備的，其他則可以選填。

若您需要自訂本頁網址，可使用 Slug: 定義。

4. 貼圖與內部檔案連結

為使目錄看起來整齊一些，首先我們在 ./content/ 目錄下新增兩個目錄：files 與 images （名稱可以任意取），然後在 pelicanconf.py 下新增變數：

STATIC_PATHS = ['images', 'files']

接著只要使用 reStructuredText 或 Markdown 的標準貼圖與內部連結語法即可。

5. 產生 html

非常簡單，一行指令即可完成：

make html

輸出的檔案位於 ./output/ 目錄下。