设置

Pelican可以通过配置文件进行配置，你可以使用以下的命令在指定配置文件:

$ pelican -s path/to/your/settingsfile.py path

配置通过Python模块（即一个Python文件）的方式实现。这里有一个配置文件的例子 /samples/pelican.conf.py

所有的配置项必须采用大写字母，否则他们将不起任何左右。

所有配置文件中的配置项，都会传递给模板，这样你就可以使用这些配置项来添加整站范围 的内容。

以下是Pelican配置项清单：

基本配置

配置名称 (默认值)	说明
AUTHOR	默认作者 (填上你的名字)
DATE_FORMATS ({})	如果你使用了多种语言，你可以在这里设置日期格式 详情参见 “日期与区域”
DEFAULT_CATEGORY ('misc')	默认文章分类
DEFAULT_DATE_FORMAT ('%a %d %B %Y')	默认日期格式
DISPLAY_PAGES_ON_MENU (True)	是否在菜单上显示页面 模板可以选择是否使用改配置项
FALLBACK_ON_FS_DATE (True)	如果为 True ，将使用文件系统中的文件修改时间作为默认的文件发表时间
JINJA_EXTENSIONS ([])	使用的Jinja扩展的列表
DELETE_OUTPUT_DIRECTORY (False)	生成文件时是否删除 output 目录
LOCALE (‘’[1])	设置区域。可以设置一个区域列表，也可以设置一个单独的区域。 当设置为一格区域列表时，程序会尝试所有的区域，指定有一个被设置成功 为止。
MARKUP (('rst', 'md'))	可以使用的标记语言列表。当前只能选择 rst 和 md。
MD_EXTENSIONS (['codehilite','extra'])	Markdown处理器使用的扩展列表。具体可以查看Python-Markdown文档。
OUTPUT_PATH ('output/')	文件生成目录
PATH (None)	输入文件目录
PAGE_DIR ('pages')	页面输入文件目录
PAGE_EXCLUDES (())	查找页面时需要忽略的文件夹列表
ARTICLE_DIR ('')	文章输入文件目录
ARTICLE_EXCLUDES: (('pages',))	查找文章时需要忽略的文件夹列表
PDF_GENERATOR (False)	设置为 True 如果需要生成PDF文件。必须安装 rst2pdf。
RELATIVE_URLS (True)	是指Pelican是否采用相对路径。
PLUGINS ([])	需要加载的插件。详见 plugin.
SITENAME ('A Pelican Blog')	站点名称
SITEURL	站点URL。默认没有配置时，假设URL为根目录为 “/” 的相对路径。 设置 SITEURL 时，不要将最好的 “/” 去掉。站点的URL将会以绝对路径 的形式生成。如果你不想使用相对根目录的路径或绝对路径，你可以通过设置 RELATIVE_URL 来实现。
STATIC_PATHS (['images'])	输出路径中文件访问的静态文件路径。默认的，Pelican会将 images 文件 夹拷贝到 output 文件夹中去。
TIMEZONE	显示文章时间和Atom，RSS时间的时区信息。详见 “timezone” 一节。
TYPOGRIFY (False)	如果设置为 Ture ，在生成HTML过程中将使用`Typogrify <http://static.mintchaos.com/projects/typogrify/>`_ 来进行以下额外的转换。
LESS_GENERATOR (FALSE)	设置为 True 或指向 lessc 的路径时（当其不在系统路径中时） 允许编译less文件。需要安装 less css 。
DIRECT_TEMPLATES (('index', 'tags', 'categories', 'archives'))	用于直接渲染内容的模板列表。一般来说，这些模板用于生成索引页， 如：标签，类目，主页等。
PAGINATED_DIRECT_TEMPLATES (('index',))	需要使用标页数的模板。
SUMMARY_MAX_LENGTH (50)	文章简介的默认长度。当你的文章没有指定简介是使用。如果设置为 null 表示将原文作为简介。

[1]	默认为系统的区域设置

设置URL

You can customize the URLs and locations where files will be saved. The URLs and SAVE_AS variables use Python’s format strings. These variables allow you to place your articles in a location such as ‘{slug}/index.html’ and link to them as ‘{slug}’ for clean URLs. These settings give you the flexibility to place your articles and pages anywhere you want.

你可以自定义URL和文件放置的位置。 URL 和 SAVE_AS 参数将使用Python的格式化字符串 来表示。这些参数允许你自定义文章的放置位置，如 ‘{slug}/index.html’ 或者简单的使用 ‘{slug}’来作为URL。这些设置让你可以更灵活的按照你的意愿来放置文章和页面。

查看更多关于Python日期的信息 http://bit.ly/cNcJUC 。

同样的，你可以使用其他文件元信息:

• slug
• date
• lang
• author
• category

例如:

• ARTICLE_URL = ‘posts/{date:%Y}/{date:%b}/{date:%d}/{slug}/’
• ARTICLE_SAVE_AS = ‘posts/{date:%Y}/{date:%b}/{date:%d}/{slug}/index.html’

这将保存你的输出文件到路径 ‘/posts/2011/Aug/07/sample-post/index.html’, 且它的URL是 ‘/posts/2011/Aug/07/sample-post/’.

配置名称 (默认值)	说明
ARTICLE_URL (‘{slug}.html’)	文章的URL。
ARTICLE_SAVE_AS (‘{slug}.html’)	文章的保存路径。
ARTICLE_LANG_URL (‘{slug}-{lang}.html’)	非默认语言的文章的URL。
ARTICLE_LANG_SAVE_AS (‘{slug}-{lang}.html’	非默认语言的文章的保存路径。
PAGE_URL (‘pages/{slug}.html’)	页面的URL
PAGE_SAVE_AS (‘pages/{slug}.html’)	页面的保存路径。
PAGE_LANG_URL (‘pages/{slug}-{lang}.html’)	非默认语言的页面的URL。
PAGE_LANG_SAVE_AS (‘pages/{slug}-{lang}.html’)	非默认语言的页面的保存路径。
AUTHOR_URL (‘author/{name}.html’)	作者页面URL。
AUTHOR_SAVE_AS (‘author/{name}.html’)	作者页面保存路径。
CATEGORY_URL (‘category/{name}.html’)	类目页面URL。
CATEGORY_SAVE_AS (‘category/{name}.html’)	类目页面保存路径。
TAG_URL (‘tag/{name}.html’)	标签页URL。
TAG_SAVE_AS (‘tag/{name}.html’)	标签页保存路径。
<DIRECT_TEMPLATE_NAME>_SAVE_AS	直接展示的页面的保存路径，其中 <DIRECT_TEMPLATE_NAME> 是其模板名称的大写。

Timezone

If no timezone is defined, UTC is assumed. This means that the generated Atom and RSS feeds will contain incorrect date information if your locale is not UTC.

Pelican issues a warning in case this setting is not defined, as it was not mandatory in previous versions.

Have a look at the wikipedia page to get a list of valid timezone values.

Date format and locale

If no DATE_FORMAT is set, fall back to DEFAULT_DATE_FORMAT. If you need to maintain multiple languages with different date formats, you can set this dict using language name (lang in your posts) as key. Regarding available format codes, see strftime document of python :

DATE_FORMAT = {
    'en': '%a, %d %b %Y',
    'jp': '%Y-%m-%d(%a)',
}

You can set locale to further control date format:

LOCALE = ('usa', 'jpn',  # On Windows
    'en_US', 'ja_JP'     # On Unix/Linux
    )

Also, it is possible to set different locale settings for each language. If you put (locale, format) tuples in the dict, this will override the LOCALE setting above:

# On Unix/Linux
DATE_FORMAT = {
    'en': ('en_US','%a, %d %b %Y'),
    'jp': ('ja_JP','%Y-%m-%d(%a)'),
}

# On Windows
DATE_FORMAT = {
    'en': ('usa','%a, %d %b %Y'),
    'jp': ('jpn','%Y-%m-%d(%a)'),
}

This is a list of available locales on Windows . On Unix/Linux, usually you can get a list of available locales via the locale -a command; see manpage locale(1) for more information.

Feed settings

By default, Pelican uses Atom feeds. However, it is also possible to use RSS feeds if you prefer.

Pelican generates category feeds as well as feeds for all your articles. It does not generate feeds for tags by default, but it is possible to do so using the TAG_FEED and TAG_FEED_RSS settings:

Setting name (default value)	What does it do?
FEED_DOMAIN (None, i.e. base URL is “/”)	The domain prepended to feed URLs. Since feed URLs should always be absolute, it is highly recommended to define this (e.g., “http://feeds.example.com”). If you have already explicitly defined SITEURL (see above) and want to use the same domain for your feeds, you can just set: FEED_DOMAIN = SITEURL
FEED ('feeds/all.atom.xml')	Relative URL to output the Atom feed.
FEED_RSS (None, i.e. no RSS)	Relative URL to output the RSS feed.
CATEGORY_FEED (‘feeds/%s.atom.xml’[2])	Where to put the category Atom feeds.
CATEGORY_FEED_RSS (None, i.e. no RSS)	Where to put the category RSS feeds.
TAG_FEED (None, i.e. no tag feed)	Relative URL to output the tag Atom feed. It should be defined using a “%s” match in the tag name.
TAG_FEED_RSS (None, ie no RSS tag feed)	Relative URL to output the tag RSS feed
FEED_MAX_ITEMS	Maximum number of items allowed in a feed. Feed item quantity is unrestricted by default.

If you don’t want to generate some of these feeds, set None to the variables above.

[2]	%s is the name of the category.

FeedBurner

If you want to use FeedBurner for your feed, you will likely need to decide upon a unique identifier. For example, if your site were called “Thyme” and hosted on the www.example.com domain, you might use “thymefeeds” as your unique identifier, which we’ll use throughout this section for illustrative purposes. In your Pelican settings, set the FEED attribute to “thymefeeds/main.xml” to create an Atom feed with an original address of http://www.example.com/thymefeeds/main.xml. Set the FEED_DOMAIN attribute to http://feeds.feedburner.com, or http://feeds.example.com if you are using a CNAME on your own domain (i.e., FeedBurner’s “MyBrand” feature).

There are two fields to configure in the FeedBurner interface: “Original Feed” and “Feed Address”. In this example, the “Original Feed” would be http://www.example.com/thymefeeds/main.xml and the “Feed Address” suffix would be thymefeeds/main.xml.

Pagination

The default behaviour of Pelican is to list all the article titles along with a short description on the index page. While it works pretty well for small-to-medium blogs, for sites with large quantity of articles it would be convenient to have a way to paginate the list.

You can use the following settings to configure the pagination.

Setting name (default value)	What does it do?
DEFAULT_ORPHANS (0)	The minimum number of articles allowed on the last page. Use this when you don’t want to have a last page with very few articles.
DEFAULT_PAGINATION (False)	The maximum number of articles to include on a page, not including orphans. False to disable pagination.

Tag cloud

If you want to generate a tag cloud with all your tags, you can do so using the following settings.

Setting name (default value)	What does it do?
TAG_CLOUD_STEPS (4)	Count of different font sizes in the tag cloud.
TAG_CLOUD_MAX_ITEMS (100)	Maximum number of tags in the cloud.

The default theme does not support tag clouds, but it is pretty easy to add:

<ul>
    {% for tag in tag_cloud %}
        <li class="tag-{{ tag.1 }}"><a href="/tag/{{ tag.0 }}/">{{ tag.0 }}</a></li>
    {% endfor %}
</ul>

You should then also define a CSS style with the appropriate classes (tag-0 to tag-N, where N matches TAG_CLOUD_STEPS -1).

Translations

Pelican offers a way to translate articles. See the Getting Started section for more information.

Setting name (default value)	What does it do?
DEFAULT_LANG ('en')	The default language to use.
TRANSLATION_FEED (‘feeds/all-%s.atom.xml’[3])	Where to put the feed for translations.

[3]	%s is the language

Ordering content

Setting name (default value)	What does it do?
REVERSE_ARCHIVE_ORDER (False)	Reverse the archives list order. (True: orders by date in descending order, with newer articles first.)
REVERSE_CATEGORY_ORDER (False)	Reverse the category order. (True: lists by reverse alphabetical order; default lists alphabetically.)

Theming

Theming is addressed in a dedicated section (see How to create themes for Pelican). However, here are the settings that are related to theming.

Setting name (default value)	What does it do?
THEME	Theme to use to produce the output. Can be the complete static path to a theme folder, or chosen between the list of default themes (see below)
THEME_STATIC_PATHS (['static'])	Static theme paths you want to copy. Default value is static, but if your theme has other static paths, you can put them here.
CSS_FILE ('main.css')	Specify the CSS file you want to load.
WEBASSETS (False)	Asset management with webassets (see below)

By default, two themes are available. You can specify them using the -t option:

• notmyidea
• simple (a synonym for “full text” :)

You can define your own theme too, and specify its placement in the same manner. (Be sure to specify the full absolute path to it.)

Here is a guide on how to create your theme

You can find a list of themes at http://github.com/ametaireau/pelican-themes.

Pelican comes with pelican-themes, a small script for managing themes.

The notmyidea theme can make good use of the following settings. I recommend using them in your themes as well.

Setting name	What does it do ?
DISQUS_SITENAME	Pelican can handle Disqus comments. Specify the Disqus sitename identifier here.
GITHUB_URL	Your GitHub URL (if you have one). It will then use this information to create a GitHub ribbon.
GOOGLE_ANALYTICS	‘UA-XXXX-YYYY’ to activate Google Analytics.
GOSQUARED_SITENAME	‘XXX-YYYYYY-X’ to activate GoSquared.
MENUITEMS	A list of tuples (Title, URL) for additional menu items to appear at the beginning of the main menu.
PIWIK_URL	URL to your Piwik server - without ‘http://‘ at the beginning.
PIWIK_SSL_URL	If the SSL-URL differs from the normal Piwik-URL you have to include this setting too. (optional)
PIWIK_SITE_ID	ID for the monitored website. You can find the ID in the Piwik admin interface > settings > websites.
LINKS	A list of tuples (Title, URL) for links to appear on the header.
SOCIAL	A list of tuples (Title, URL) to appear in the “social” section.
TWITTER_USERNAME	Allows for adding a button to articles to encourage others to tweet about them. Add your Twitter username if you want this button to appear.

In addition, you can use the “wide” version of the notmyidea theme by adding the following to your configuration:

CSS_FILE = "wide.css"

Asset management

The WEBASSETS setting allows to use the webassets module to manage assets (css, js). The module must first be installed:

pip install webassets

webassets allows to concatenate your assets and to use almost all of the hype tools of the moment (see the documentation):

• css minifier (cssmin, yuicompressor, ...)
• css compiler (less, sass, ...)
• js minifier (uglifyjs, yuicompressor, closure, ...)

Others filters include gzip compression, integration of images in css with datauri and more. Webassets also append a version identifier to your asset url to convince browsers to download new versions of your assets when you use far future expires headers.

When using it with Pelican, webassets is configured to process assets in the OUTPUT_PATH/theme directory. You can use it in your templates with a template tag, for example:

{% assets filters="cssmin", output="css/style.min.css", "css/inuit.css", "css/pygment-monokai.css", "css/main.css" %}
    <link rel="stylesheet" href="{{ ASSET_URL }}">
{% endassets %}

will produce a minified css file with the version identifier:

<link href="http://{SITEURL}/theme/css/style.min.css?b3a7c807" rel="stylesheet">

Another example for javascript:

{% assets filters="uglifyjs,gzip", output="js/packed.js", "js/jquery.js", "js/base.js", "js/widgets.js" %}
    <script src="{{ ASSETS_URL }}"></script>
{% endassets %}

will produce a minified and gzipped js file:

<script src="http://{SITEURL}/theme/js/packed.js?00703b9d"></script>

Example settings