Pelican 3.7.1¶

安装¶

安装Pelican(如果您打算用Markdown的话,请一并安装),需要Python2.7.x或者Python3.3+的运行环境.在您习惯的终端里面,输入下面的命令.如果需要权限的话,加上sudo:

pip install pelican markdown

创建一个项目¶

首先，为您的项目选择名称，为您的站点起一个名字，然后切换到该目录：

mkdir -p ~/projects/yoursite
cd ~/projects/yoursite

通过pelican-quickstart命令创建一个项目框架，首先Pelican会询问有关您网站的一些问题：

pelican-quickstart

有些问题后面的中括号里面给出了默认值，您可以直接敲回车,接受这些默认值[1]。当您询问您的网址前缀时，请按照指示输入您的域名（例如，http://example.com）。

Create an article¶

如果您什么都没写，您无法运行Pelican。使用您喜欢的文本编辑器创建您的第一篇文章，其中包含以下内容：

Title: My First Review
Date: 2010-12-03 10:20
Category: Review

Following is a review of my favorite mechanical keyboard.

鉴于此示例文章采用Markdown格式，请将其另存为~/projects/yoursite/content/keyboard-review.md。

生成你的网站¶

从您的站点目录中，运行Pelican命令来生成您的站点：

pelican content

您的网站现已在output目录中生成。（您可能会看到与Feed相关的警告，但在本地开发时是正常现象，可以忽略）。

预览您的网站¶

打开一个新的终端会话并运行以下命令切换到output目录并启动Pelican的Web服务器：

cd ~/projects/yoursite/output
python -m pelican.server

浏览器中访问http://localhost:8000/来预览您的网站。

继续阅读其他文档部分了解更多详细信息，并查看Pelican wiki的教程页面以获取社区发布的教程的链接。

脚注¶

可选包¶

如果您打算使用Markdown作为标记格式，则需要安装Markdown库：

pip install Markdown

可以在设置文件中启用排印增强功能，但首先必须安装必需的Typogrify库：

pip install typogrify

Dependencies¶

When Pelican is installed, the following dependent Python packages should be automatically installed without any action on your part:

• feedgenerator, to generate the Atom feeds
• jinja2, for templating support
• pygments, for syntax highlighting
• docutils, for supporting reStructuredText as an input format
• pytz, for timezone definitions
• blinker, an object-to-object and broadcast signaling system
• unidecode, for ASCII transliterations of Unicode text
• six, for Python 2 and 3 compatibility utilities
• MarkupSafe, for a markup safe string implementation
• python-dateutil, to read the date metadata

Upgrading¶

If you installed a stable Pelican release via pip and wish to upgrade to the latest stable release, you can do so by adding --upgrade:

pip install --upgrade pelican

If you installed Pelican via distutils or the bleeding-edge method, simply perform the same step to install the most recent version.

Kickstart your site¶

Once Pelican has been installed, you can create a skeleton project via the pelican-quickstart command, which begins by asking some questions about your site:

pelican-quickstart

Once you finish answering all the questions, your project will consist of the following hierarchy (except for pages — shown in parentheses below — which you can optionally add yourself if you plan to create non-chronological content):

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

下一步是开始向已经为您创建好的content文件夹添加文章。

文章与页面¶

Pelican认为“文章”是按时间顺序的内容，例如博客上的帖子，因此与日期相关联。

“页面”的想法是，它们通常与时间无关，并且用于不经常变化的内容（例如，“关于”或“联系方式”页面）。

您可以在仓库中找到样本内容：pelican/samples/content/

文件元数据¶

Pelican尝试尽力从文件系统（例如，您的文章的类别）获取所需的信息，但还是需要在文件中以元数据形式提供的一些信息。

如果您以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

作者和标签列表可以分号分隔，这样可以编写包含逗号的作者和标签：

:tags: pelican, publishing tool; pelican, bird
:authors: Metaireau, Alexis; Doyle, Conan

Pelican实现对reStructuredText的扩展，以支持abbr HTML标签。要使用它，在你的文章中写这样的东西：

This will be turned into :abbr:`HTML (HyperText Markup Language)`.

您还可以使用Markdown语法（文件以.md，.markdown，.mkd或.mdown ）。Markdown生成需要您首先显式安装Markdown程序包，可以通过pip 安装 Markdown 。

Pelican还支持Markdown Extensions，如果它们不包含在默认的Markdown包中，可能需要单独安装，并且可以通过MARKDOWN 设置。

Markdown文章的元数据语法应遵循以下模式：

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.

Readers for additional formats (such as AsciiDoc) are available via plugins. Refer to pelican-plugins repository for those.

Pelican还可以处理以.html和.htm结尾的HTML文件。Pelican以非常简单的方式解释HTML，从meta标签读取元数据，从title标签中获取标题，从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，标准元数据有一个简单的例外：tag可以通过tag元数据指定，如Pelican中的标准，或者通过keywords元数据，如HTML中的标准。这两个可以互换使用。

请注意，除了标题之外，这篇文章的元数据不是强制性的：如果未指定日期，并且DEFAULT_DATE设置为'fs'，则Pelican将依靠文件的“mtime”时间戳，类别可以由文件所在的目录来确定。例如，位于python/foobar/myfoobar.rst的文件将具有foobar的分类。如果要以其他方式组织文件，其文件夹的名称不是一个好的分类名称，则可以将USE_FOLDER_AS_CATEGORY设置为False。在解析页面元数据中给出的日期时，Pelican支持W3C的建议子集ISO 8601。

modified应该是上次更新文章的时间，如果没有指定，则默认为date。此外，您可以在模板中显示modified，当您修改文章后，当您将modified设置为当前日期时，Feed阅读器中的Feed条目将自动更新。

authors是文章作者的逗号分隔列表。如果只有一个作者可以使用author字段。

如果没有明确指定给定帖子的摘要元数据，则SUMMARY_MAX_LENGTH设置可用于指定从文章开头使用多少个词作为摘要。

您还可以通过要在FILENAME_METADATA设置中设置的正则表达式从文件名中提取任何元数据。匹配的所有命名组将在元数据对象中设置。FILENAME_METADATA设置的默认值将仅从文件名中提取日期。例如，如果要同时提取日期和slug,您可以这样设置:'(?P<date>\d{4}-\d{2}-\d{2})_(?P<slug>.*)'

请注意，文件中可用的元数据优先于从文件名中提取的元数据。

页面¶

如果您在内容文件夹中创建一个名为pages的文件夹，则其中的所有文件将用于生成静态页面，例如About或Contact页面。（请参阅下面的示例文件系统布局。）

您可以使用DISPLAY_PAGES_ON_MENU设置来控制是否在主导航菜单中显示所有页面。（默认值为True。）

如果要排除任何页面链接到菜单中或列在菜单中，请将Status: hidden属性添加到其元数据中。如果您希望自定义错误页面,那么这将非常有用.

链接到内部内容¶

从Pelican3.1起，现在可以在源内容层次结构中指定文件的站点内链接，而不是生成的层次结构中的文件。这样可以更容易地将当前帖子与可能与该帖子一起坐的其他内容进行链接（而不必确定站点生成后将放置其他内容的位置）。

链接到内部内容(content中的文件)的语法是:{filename}path/to/file.注意,{filename}中的路径分隔符请采用斜线/,即使您是在Windows操作系统中.

例如，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)

content
├── images
│   └── han.jpg
├── pdfs
│   └── menu.pdf
└── pages
    └── test.md

![Alt Text]({filename}/images/han.jpg)
[Our Menu]({filename}/pdfs/menu.pdf)

STATIC_PATHS = ['images', 'pdfs']

content
├── blog
│   ├── icons
│   │   └── icon.png
│   ├── photo.jpg
│   └── testpost.md
└── downloads
    └── archive.zip

PATH = 'content'
STATIC_PATHS = ['blog', 'downloads']
ARTICLE_PATHS = ['blog']
ARTICLE_SAVE_AS = '{date:%Y}/{slug}.html'
ARTICLE_URL = '{date:%Y}/{slug}.html'

Title: Test Post
Category: test
Date: 2014-10-31

![Icon]({attach}icons/icon.png)
![Photo]({attach}photo.jpg)
[Downloadable File]({attach}/downloads/archive.zip)

output
└── 2014
    ├── archive.zip
    ├── icons
    │   └── icon.png
    ├── photo.jpg
    └── test-post.html

导入现有站点¶

可以使用简单的脚本从WordPress，Tumblr，Dotclear和RSS feeds导入您的站点。See Importing an existing site.

翻译¶

翻译文章是可行的.为此，您需要向您的文章/页面添加lang元属性，并设置DEFAULT_LANG设置（默认为英文[en]）。使用这些设置，只列出具有默认语言的文章，每篇文章将附有该文章的可用翻译列表。

Pelican使用文章的URL“slug”来确定两个或更多个文章是否是彼此的翻译。可以在文件的元数据中手动设置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设置检测到一个特定文章的原始版本，请使用translation元数据指定哪些帖子是翻译：

Foobar is not dead
##################

:slug: foobar-is-not-dead
:lang: en
:translation: true

That's true, foobar is still alive!

语法高亮显示¶

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.")

指定的标识符(例如,python,ruby)应该在可用词法分析器中.

当使用reStructuredText时，code-block指令中提供了以下选项：

请注意，根据版本，您的Pygments模块可能没有所有这些选项可用。有关每个选项的更多详细信息，请参阅Pygments文档的HtmlFormatter部分。

例如，以下代码块启用行号，从153开始，并将带有pgcss的Pygments CSS类前缀，使名称更加独特，并避免可能的CSS冲突：

.. code-block:: identifier
    :classprefix: pgcss
    :linenos: table
    :linenostart: 153

   <indented code block goes here>

也可以在Pelican设置文件中指定PYGMENTS_RST_OPTIONS变量,以包含将自动应用于每个代码块的选项。

例如，如果要为每个代码块和CSS前缀显示行号，您可以将此变量设置为：

PYGMENTS_RST_OPTIONS = {'classprefix': 'pgcss', 'linenos': 'table'}

如果指定，单个代码块的设置将覆盖设置文件中的默认值。

发布草稿¶

如果您想以草稿的形式发布文章（例如，为了让朋友在发布前进行审核），您可以添加Status: draft属性到其元数据。然后，该文章将被输出到draft文件夹，而不是在索引页面上或任何分类或标签页面上列出。

如果您的文章应该自动发布为草稿（在文章完成之前不要意外发布文章），请将其状态包含在DEFAULT_METADATA中：

DEFAULT_METADATA = {
    'status': 'draft',
}

要在默认状态为draft时发布帖子，请更新帖子的元数据以包含Status: published。

站点生成¶

一旦Pelican安装并且您有一些内容（例如，以Markdown或reST格式），您可以通过pelican命令将您的内容转换为HTML，指定内容的路径，（可选）路径到您的设置文件：

pelican /path/to/your/content/ [-s path/to/your/settings.py]

上述命令将生成您的站点并将其保存在output/文件夹中，使用默认主题生成一个简单的站点。默认主题由非常简单的HTML组成，没有样式，所以人们可以将其用作创建自己的主题的基础。

当在单个文章或页面上工作时，可以仅生成与该内容对应的文件。为此，请使用--write-selected参数，如下所示：

pelican --write-selected output/posts/my-post-title.html

请注意，您必须指定生成的output文件的路径，而不是源内容。要确定输出文件路径，请使用-debug标志来确定正确的文件名和位置。如果需要， --write-selected可以以逗号分隔的路径列表，或者可以配置为设置。（见：只写选择的内容）

您也可以告诉Pelican观看您的修改，而不是每次要查看更改时手动重新运行它。要启用此功能，请使用-r或--autoreload选项运行Pelican命令。

Pelican有其他命令行开关可用。看看帮助，看看你可以使用的所有选项：

pelican --help

firefox output/index.html

cd output
python -m SimpleHTTPServer

cd output
python -m http.server

部署¶

生成网站后，在本地开发环境中进行预览，并准备将其部署到生产环境中，您可能会首先使用任何特定于生产的设置重新生成您的站点（例如，分析Feed等）你可能已经定义了：

pelican content -s publishconf.py

要使您的发布配置在您的pelicanconf.py之上，您可以通过在publishconf.py中包含以下行来导入pelicanconf设置。 ：

from pelicanconf import *

如果您使用pelican-quickstart生成了publishconf.py，则默认情况下会包含该行。

部署您的站点的步骤将取决于它将在哪里托管。如果您有SSH访问运行Nginx或Apache的服务器，则可以使用rsync工具传输您的站点文件：

rsync -avc --delete output/ host.example.com:/var/www/your-site/

还有许多其他部署选项，其中一些可以通过pelican-quickstart命令首次设置您的站点时进行配置。有关通过GitHub页面发布的详细信息，请参阅提示页面。

自动化¶

虽然Pelican命令是生成您的站点的规范方式，但可以使用自动化工具来简化生成和发布流程。在pelican-quickstart过程中提出的问题之一涉及您是否要自动化站点生成和发布。如果您对该问题回答“是”，将在项目的根目录中生成fabfile.py和Makefile。这些文件预先填充了在Pelican快速入门过程中提供的其他答案中收集的某些信息，这些文件是作为起点，应该根据您的特定需求和使用模式进行定制。如果您发现某个自动化程序并不是那么实用，那么您可以随时删除那个程序，那并不会影响标准的Pelican命令的使用。

以下是“包装”Pelican命令的自动化工具，可以简化生成，预览和上传网站的过程。

pip install Fabric

fab build

fab regenerate

fab serve

fab publish

make html

make publish

make regenerate

make serve

make devserver

./develop_server.sh stop

make rsync_upload

基本设定¶

USE_FOLDER_AS_CATEGORY = True

当您不打算在帖子元数据中指定分类时，请将此设置设置为True，然后在子文件夹中组织文章，子文件夹将成为您的帖子的分类。如果设置为False，则将使用DEFAULT_CATEGORY作为后备。

DEFAULT_CATEGORY = 'misc'

默认的分类值.

DISPLAY_PAGES_ON_MENU = True

是否在模板的菜单上显示页面。某些模板可能并不会采用这个配置.

DISPLAY_CATEGORIES_ON_MENU = True

是否在模板的菜单上显示类别。模板可能不会采用此设置。

DOCUTILS_SETTINGS = {}

docutils发布商的额外配置设置（仅适用于reStructuredText）。有关详细信息，请参阅Docutils配置设置。

DELETE_OUTPUT_DIRECTORY = False

在生成新文件之前删除其内容的输出目录和里面的全部内容。这可以有助于防止较旧的不必要的文件持续存在于输出中。但是，这是一个破坏性的设置，应该非常小心。

OUTPUT_RETENTION = []

应该保留并且不会从输出目录中删除的文件名列表。一个用例是保存版本控制数据。

例：

OUTPUT_RETENTION = [".hg", ".git", ".bzr"]

JINJA_ENVIRONMENT = {'trim_blocks': True, 'lstrip_blocks': True}

一个您要使用的自定义Jinja2环境变量的字典。这还包括您可能想要包括的扩展列表。见Jinja环境文件。

JINJA_FILTERS = {}

您要使用的自定义Jinja2过滤器的字典。字典应该将filtername映射到过滤器函数。

例：

JINJA_FILTERS = {'urlencode': urlencode_filter}

请参阅Jinja自定义过滤器文档。

LOG_FILTER = []

包含记录级别（最多警告）的元组列表和要忽略的消息。

例：

LOG_FILTER = [(logging.WARN, 'TAG_SAVE_AS is set to False')]

READERS = {}

pelican文件扩展名/阅读器类的字典，用于处理或忽略。

例如，为避免处理.html文件，请设置：

READERS = {'html': None}

要为foo扩展名添加自定义阅读器，请设置：

READERS = {'foo': FooReader}

IGNORE_FILES = ['.#*']

glob模式列表。与这些模式匹配的文件和目录将被处理器忽略。例如,默认的['.#*']将会忽略emacs的锁文件,而['__pycache__']将会忽略Python3 的二进制文件.

MARKDOWN = {...}

Markdown处理器的额外配置设置。有关支持的选项的完整列表，请参阅Python Markdown文档的选项部分。extensions选项将从extension_configs选项自动计算。

默认为：

MARKDOWN = {
    'extension_configs': {
        'markdown.extensions.codehilite': {'css_class': 'highlight'},
        'markdown.extensions.extra': {},
        'markdown.extensions.meta': {},
    },
    'output_format': 'html5',
}

注意

在您的设置文件中定义的字典将更新此默认字典。

OUTPUT_PATH = 'output/'

在哪里输出生成的文件。

PATH¶

由Pelican处理的内容目录的路径。如果未定义，并且内容路径未通过Pelican命令的参数指定，则Pelican将使用当前工作目录。

PAGE_PATHS = ['pages']

相对于PATH，可以查看页面的目录和文件列表。

PAGE_EXCLUDES = []

在ARTICLE_PATHS之外，查找页面时要排除的目录列表。

ARTICLE_PATHS = ['']

相对于PATH，查看文章的目录和文件列表。

ARTICLE_EXCLUDES = []

除了PAGE_PATHS之外，在查找文章时要排除的目录列表。

OUTPUT_SOURCES = False

如果要将其原始格式的文章和页面（例如Markdown或reStructuredText）复制到指定的OUTPUT_PATH，请设置为True。

OUTPUT_SOURCES_EXTENSION = '.text'

控制SourcesGenerator将使用的扩展名。默认为.text。如果不是有效的字符串，将使用默认值。

PLUGINS = []

要加载的插件列表。见插件。

PLUGIN_PATHS = []

查找插件的目录列表。See Plugins.

SITENAME = 'A Pelican Blog'

您的网站名称

SITEURL¶

您的网站的基本URL。默认情况下未定义，因此最好指定您的SITEURL；如果没有，则不会使用正确形式的URL生成Feed。您应该包括http://和您的域，最后没有尾部斜杠。例如：SITEURL = 'http://mydomain.com'

STATIC_PATHS = ['images']

要查找静态文件的目录列表（相对于PATH）。这样的文件将被复制到输出目录而不进行修改。文章,页面和其他的内容源文件将会被自动跳过,所以,一个目录同时出现在这里,PAGE_PATHS和ARTICLE_PATHS是可以的.Pelican的默认设置包括“images”目录。

STATIC_EXCLUDES = []

查找静态文件时要排除的目录列表。

STATIC_EXCLUDE_SOURCES = True

如果设置为False，则在复制STATIC_PATHS中找到的文件时，不会跳过内容源文件。此设置是为了与版本3.5之前的Pelican版本向后兼容。除非STATIC_PATHS包含也在ARTICLE_PATHS或PAGE_PATHS中的目录，否则它不起作用。如果您要发布网站的源文件，请考虑使用OUTPUT_SOURCES设置。

TYPOGRIFY = False

如果设置为True，则可以通过Typogrify库将生成的HTML中的几个排版改进内容并入，该库可通过以下方式安装：pip install typogrify

TYPOGRIFY_IGNORE_TAGS = []

Typogrify忽略的标签列表。默认情况下，Typogrify将忽略pre和code标签。这需要安装Typogrify版本2.0.4或更高版本

SUMMARY_MAX_LENGTH = 50

创建文章的简短摘要时，这将是创建的文本的默认长度（以字为单位）。这仅适用于您的内容没有另外指定摘要。设置为None将使摘要成为原始内容的副本。

WITH_FUTURE_DATES = True

如果禁用，日后的内容将默认为draft。请参阅仅阅读修改内容以获取警告。

INTRASITE_LINK_REGEX = '[{|](?P<what>.*?)[|}]'

用于解析内部链接的正则表达式。链接到内部文件，标签等时的默认语法是在{}或||中包含标识符，例如filename。{和}之间的标识符进入what捕获组。有关详细信息，请参见链接到内部内容。

PYGMENTS_RST_OPTIONS = []

您的reStructuredText代码块的默认Pygments设置列表。有关支持的选项列表，请参见语法高亮显示。

SLUGIFY_SOURCE = 'title'

指定要从哪里自动生成slug。可以将title设置为使用“Title:”元数据标签或basename在创建小插件时使用文章的文件名。

CACHE_CONTENT = False

如果True，将内容保存在缓存中。有关缓存的详细信息，请参阅仅读取修改内容。

CONTENT_CACHING_LAYER = 'reader'

如果设置为'reader'，则只保存读者返回的原始内容和元数据。如果设置为'generator'，则保存已处理的内容对象。

CACHE_PATH = 'cache'

用于存储缓存文件的目录。

GZIP_CACHE = True

如果True，请使用gzip压缩缓存文件。

CHECK_MODIFIED_METHOD = 'mtime'

控制如何检查文件的修改。

LOAD_CONTENT_CACHE = False

如果True，请从缓存加载未修改的内容。

WRITE_SELECTED = []

如果此列表不为空，则仅输出文件及其列表中的路径。路径应该是绝对的或相对于当前的pelican工作目录。For possible use cases see Writing only selected content.

FORMATTED_FIELDS = ['summary']

包含要解析并转换为HTML的reST / Markdown内容的元数据字段列表。

URL settings¶

首先要了解的是，现在有两种支持的URL形成方式：relative和absolute。相对URL在本地进行测试时非常有用，绝对URL是可靠的，在发布时最有用。支持两者的一种方法是具有一个Pelican配置文件用于本地开发，另一种用于发布。要查看此类设置的示例，请使用安装部分中所述的pelican-quickstart脚本，这将生成两个单独的配置文件，用于本地开发和发布，分别。

您可以自定义文件将被保存的URL和位置。* _ URL和* _ SAVE_AS变量使用Python的格式字符串。这些变量允许您将您的文章放在诸如{slug} /index.html的位置，并将其链接到{slug}以清除网址（请参见下面的示例） 。这些设置可让您灵活地将您的文章和页面放在任何地方。

Also, you can use other file metadata attributes as well:

• slug
• date
• lang
• author
• category

Example usage:

ARTICLE_URL = 'posts/{date:%Y}/{date:%b}/{date:%d}/{slug}/'
ARTICLE_SAVE_AS = 'posts/{date:%Y}/{date:%b}/{date:%d}/{slug}/index.html'
PAGE_URL = 'pages/{slug}/'
PAGE_SAVE_AS = 'pages/{slug}/index.html'

This would save your articles into something like /posts/2011/Aug/07/sample-post/index.html, save your pages into /pages/about/index.html, and render them available at URLs of /posts/2011/Aug/07/sample-post/ and /pages/about/, respectively.

RELATIVE_URLS = False

Defines whether Pelican should use document-relative URLs or not. Only set this to True when developing/testing and only if you fully understand the effect it can have on links/feeds.

ARTICLE_URL = '{slug}.html'

The URL to refer to an article.

ARTICLE_SAVE_AS = '{slug}.html'

The place where we will save an article.

ARTICLE_LANG_URL = '{slug}-{lang}.html'

The URL to refer to an article which doesn’t use the default language.

ARTICLE_LANG_SAVE_AS = '{slug}-{lang}.html'

The place where we will save an article which doesn’t use the default language.

DRAFT_URL = 'drafts/{slug}.html'

The URL to refer to an article draft.

DRAFT_SAVE_AS = 'drafts/{slug}.html'

The place where we will save an article draft.

DRAFT_LANG_URL = 'drafts/{slug}-{lang}.html'

The URL to refer to an article draft which doesn’t use the default language.

DRAFT_LANG_SAVE_AS = 'drafts/{slug}-{lang}.html'

The place where we will save an article draft which doesn’t use the default language.

PAGE_URL = 'pages/{slug}.html'

The URL we will use to link to a page.

PAGE_SAVE_AS = 'pages/{slug}.html'

The location we will save the page. This value has to be the same as PAGE_URL or you need to use a rewrite in your server config.

PAGE_LANG_URL = 'pages/{slug}-{lang}.html'

The URL we will use to link to a page which doesn’t use the default language.

PAGE_LANG_SAVE_AS = 'pages/{slug}-{lang}.html'

The location we will save the page which doesn’t use the default language.

CATEGORY_URL = 'category/{slug}.html'

The URL to use for a category.

CATEGORY_SAVE_AS = 'category/{slug}.html'

The location to save a category.

TAG_URL = 'tag/{slug}.html'

The URL to use for a tag.

TAG_SAVE_AS = 'tag/{slug}.html'

The location to save the tag page.

AUTHOR_URL = 'author/{slug}.html'

The URL to use for an author.

AUTHOR_SAVE_AS = 'author/{slug}.html'

The location to save an author.

YEAR_ARCHIVE_SAVE_AS = ''

The location to save per-year archives of your posts.

MONTH_ARCHIVE_SAVE_AS = ''

The location to save per-month archives of your posts.

DAY_ARCHIVE_SAVE_AS = ''

The location to save per-day archives of your posts.

SLUG_SUBSTITUTIONS = ()

Substitutions to make prior to stripping out non-alphanumerics when generating slugs. Specified as a list of 3-tuples of (from, to, skip) which are applied in order. skip is a boolean indicating whether or not to skip replacement of non-alphanumeric characters. Useful for backward compatibility with existing URLs.

AUTHOR_SUBSTITUTIONS = ()

Substitutions for authors. SLUG_SUBSTITUTIONS is not taken into account here!

CATEGORY_SUBSTITUTIONS = ()

Added to SLUG_SUBSTITUTIONS for categories.

TAG_SUBSTITUTIONS = ()

Added to SLUG_SUBSTITUTIONS for tags.

SLUG_SUBSTITUTIONS = (('C++', 'cpp'), ('keep dot', 'keep.dot', True))

Pelican can optionally create per-year, per-month, and per-day archives of your posts. These secondary archives are disabled by default but are automatically enabled if you supply format strings for their respective _SAVE_AS settings. Period archives fit intuitively with the hierarchical model of web URLs and can make it easier for readers to navigate through the posts you’ve written over time.

Example usage:

YEAR_ARCHIVE_SAVE_AS = 'posts/{date:%Y}/index.html'
MONTH_ARCHIVE_SAVE_AS = 'posts/{date:%Y}/{date:%b}/index.html'

With these settings, Pelican will create an archive of all your posts for the year at (for instance) posts/2011/index.html and an archive of all your posts for the month at posts/2011/Aug/index.html.

DIRECT_TEMPLATES work a bit differently than noted above. Only the _SAVE_AS settings are available, but it is available for any direct template.

ARCHIVES_SAVE_AS = 'archives.html'

The location to save the article archives page.

YEAR_ARCHIVE_SAVE_AS = ''

The location to save per-year archives of your posts.

MONTH_ARCHIVE_SAVE_AS = ''

The location to save per-month archives of your posts.

DAY_ARCHIVE_SAVE_AS = ''

The location to save per-day archives of your posts.

AUTHORS_SAVE_AS = 'authors.html'

The location to save the author list.

CATEGORIES_SAVE_AS = 'categories.html'

The location to save the category list.

TAGS_SAVE_AS = 'tags.html'

The location to save the tag list.

INDEX_SAVE_AS = 'index.html'

The location to save the list of all articles.

URLs for direct template pages are theme-dependent. Some themes use corresponding *_URL setting as string, while others hard-code them: 'archives.html', 'authors.html', 'categories.html', 'tags.html'.

Time and Date¶

TIMEZONE¶

The timezone used in the date information, to generate Atom and RSS feeds.

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.

DEFAULT_DATE = None

The default date you want to use. If 'fs', Pelican will use the file system timestamp information (mtime) if it can’t get date information from the metadata. If given any other string, it will be parsed by the same method as article metadata. If set to a tuple object, the default datetime object will instead be generated by passing the tuple to the datetime.datetime constructor.

DEFAULT_DATE_FORMAT = '%a %d %B %Y'

The default date format you want to use.

DATE_FORMATS = {}

If you manage multiple languages, you can set the date formatting here.

If no DATE_FORMATS are set, Pelican will fall back to DEFAULT_DATE_FORMAT. If you need to maintain multiple languages with different date formats, you can set the DATE_FORMATS dictionary using the language name (lang metadata in your post content) as the key.

In addition to the standard C89 strftime format codes that are listed in Python strftime documentation, you can use the - character between % and the format character to remove any leading zeros. For example, %d/%m/%Y will output 01/01/2014 whereas %-d/%-m/%Y will result in 1/1/2014.

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

It is also possible to set different locale settings for each language by using a (locale, format) tuple as a dictionary value which will override the LOCALE setting:

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

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

LOCALE¶

Change the locale [1]. A list of locales can be provided here or a single string representing one locale. When providing a list, all the locales will be tried until one works.

You can set locale to further control date format:

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

For a list of available locales refer to locales on Windows or on Unix/Linux, use the locale -a command; see manpage locale(1) for more information.

模板页¶

TEMPLATE_PAGES = None

包含将使用博客条目呈现的模板页面的映射。See Template pages.

If you want to generate custom pages besides your blog entries, you can point any Jinja2 template file with a path pointing to the file and the destination path for the generated file.

For instance, if you have a blog with three static pages — a list of books, your resume, and a contact page — you could have:

TEMPLATE_PAGES = {'src/books.html': 'dest/books.html',
                  'src/resume.html': 'dest/resume.html',
                  'src/contact.html': 'dest/contact.html'}

DIRECT_TEMPLATES = ['index', 'categories', 'authors', 'archives']

List of templates that are used directly to render content. Typically direct templates are used to generate index pages for collections of content (e.g., tags and category index pages). If the tag and category collections are not needed, set DIRECT_TEMPLATES = ['index', 'archives']

PAGINATED_DIRECT_TEMPLATES = ['index']

Provides the direct templates that should be paginated.

EXTRA_TEMPLATES_PATHS = []

A list of paths you want Jinja2 to search for templates. Can be used to separate templates from the theme. Example: projects, resume, profile ... These templates need to use DIRECT_TEMPLATES setting.

Metadata¶

AUTHOR¶

Default author (usually your name).

DEFAULT_METADATA = {}

The default metadata you want to use for all articles and pages.

FILENAME_METADATA = '(?P<date>d{4}-d{2}-d{2}).*'

The regexp that will be used to extract any metadata from the filename. All named groups that are matched will be set in the metadata object. The default value will only extract the date from the filename.

For example, to extract both the date and the slug:

FILENAME_METADATA = '(?P<date>\d{4}-\d{2}-\d{2})_(?P<slug>.*)'

See also SLUGIFY_SOURCE.

PATH_METADATA = ''

Like FILENAME_METADATA, but parsed from a page’s full path relative to the content source directory.

EXTRA_PATH_METADATA = {}

Extra metadata dictionaries keyed by relative path. Relative paths require correct OS-specific directory separators (i.e. / in UNIX and \ in Windows) unlike some other Pelican file settings.

Not all metadata needs to be embedded in source file itself. For example, blog posts are often named following a YYYY-MM-DD-SLUG.rst pattern, or nested into YYYY/MM/DD-SLUG directories. To extract metadata from the filename or path, set FILENAME_METADATA or PATH_METADATA to regular expressions that use Python’s group name notation (?P<name>…). If you want to attach additional metadata but don’t want to encode it in the path, you can set EXTRA_PATH_METADATA:

EXTRA_PATH_METADATA = {
    'relative/path/to/file-1': {
        'key-1a': 'value-1a',
        'key-1b': 'value-1b',
        },
    'relative/path/to/file-2': {
        'key-2': 'value-2',
        },
    }

This can be a convenient way to shift the installed location of a particular file:

# Take advantage of the following defaults
# STATIC_SAVE_AS = '{path}'
# STATIC_URL = '{path}'
STATIC_PATHS = [
    'static/robots.txt',
    ]
EXTRA_PATH_METADATA = {
    'static/robots.txt': {'path': 'robots.txt'},
    }

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_ATOM and TAG_FEED_RSS settings:

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_ATOM = None, i.e. no Atom feed

Relative URL to output the Atom feed.

FEED_RSS = None, i.e. no RSS

Relative URL to output the RSS feed.

FEED_ALL_ATOM = 'feeds/all.atom.xml'

Relative URL to output the all-posts Atom feed: this feed will contain all posts regardless of their language.

FEED_ALL_RSS = None, i.e. no all-posts RSS

Relative URL to output the all-posts RSS feed: this feed will contain all posts regardless of their language.

CATEGORY_FEED_ATOM = 'feeds/%s.atom.xml'

Where to put the category Atom feeds. [2]

CATEGORY_FEED_RSS = None, i.e. no RSS

Where to put the category RSS feeds.

AUTHOR_FEED_ATOM = 'feeds/%s.atom.xml'

Where to put the author Atom feeds. [2]

AUTHOR_FEED_RSS = 'feeds/%s.rss.xml'

Where to put the author RSS feeds. [2]

TAG_FEED_ATOM = 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, i.e. 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.

RSS_FEED_SUMMARY_ONLY = True

Only include item summaries in the description tag of RSS feeds. If set to False, the full content will be included instead. This setting doesn’t affect Atom feeds, only RSS ones.

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

Pagination¶

The default behaviour of Pelican is to list all the article titles along with a short description on the index page. While this works well for small-to-medium sites, sites with a large quantity of articles will probably benefit from paginating this list.

You can use the following settings to configure the pagination.

DEFAULT_ORPHANS = 0

The minimum number of articles allowed on the last page. Use this when you don’t want the last page to only contain a handful of articles.

DEFAULT_PAGINATION = False

The maximum number of articles to include on a page, not including orphans. False to disable pagination.

PAGINATION_PATTERNS¶

A set of patterns that are used to determine advanced pagination output.

(minimum page, URL setting, SAVE_AS setting,)

PAGINATION_PATTERNS = (
    (1, '{base_name}/', '{base_name}/index.html'),
    (2, '{base_name}/page/{number}/', '{base_name}/page/{number}/index.html'),
)

Translations¶

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

DEFAULT_LANG = 'en'

The default language to use.

TRANSLATION_FEED_ATOM = 'feeds/all-%s.atom.xml'

Where to put the Atom feed for translations. [3]

TRANSLATION_FEED_RSS = None, i.e. no RSS

Where to put the RSS feed for translations.

Ordering content¶

NEWEST_FIRST_ARCHIVES = True

Order archives by newest first by date. (False: orders by date with older articles first.)

REVERSE_CATEGORY_ORDER = False

Reverse the category order. (True: lists by reverse alphabetical order; default lists alphabetically.)

ARTICLE_ORDER_BY = 'reversed-date'

Defines how the articles (articles_page.object_list in the template) are sorted. Valid options are: metadata as a string (use reversed- prefix the reverse the sort order), special option 'basename' which will use the basename of the file (without path) or a custom function to extract the sorting key from articles. The default value, 'reversed-date', will sort articles by date in reverse order (i.e. newest article comes first).

PAGE_ORDER_BY = 'basename'

Defines how the pages (PAGES variable in the template) are sorted. Options are same as ARTICLE_ORDER_BY. The default value, 'basename' will sort pages by their basename.

Themes¶

创建pelican主题在一个专门的部分（见创建主题）。但是，这里是与主题相关的设置。

THEME¶

主题用于产生输出的网站。可以是主题文件夹的相对或绝对路径，或通过pelican安装的默认主题或主题的名称（见下文）。

THEME_STATIC_DIR = 'theme'

输出路径中的目的地目录，Pelican将放置从THEME_STATIC_PATHS收集的文件。默认是theme。

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. If files or directories with the same names are included in the paths defined in this settings, they will be progressively overwritten.

CSS_FILE = 'main.css'

Specify the CSS file you want to load.

By default, two themes are available. You can specify them using the THEME setting or by passing the -t option to the pelican command:

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

There are a number of other themes available at https://github.com/getpelican/pelican-themes. Pelican comes with pelican-themes, a small script for managing themes.

You can define your own theme, either by starting from scratch or by duplicating and modifying a pre-existing theme. Here is a guide on how to create your theme.

Following are example ways to specify your preferred theme:

# Specify name of a built-in theme
THEME = "notmyidea"
# Specify name of a theme installed via the pelican-themes tool
THEME = "chunk"
# Specify a customized theme, via path relative to the settings file
THEME = "themes/mycustomtheme"
# Specify a customized theme, via absolute path
THEME = "/home/myuser/projects/mysite/themes/mycustomtheme"

The built-in notmyidea theme can make good use of the following settings. Feel free to use them in your themes as well.

SITESUBTITLE¶

A subtitle to appear in the header.

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¶

Set to UA-XXXXX-Y Property’s tracking ID to activate Google Analytics.

GA_COOKIE_DOMAIN¶

Set cookie domain field of Google Analytics tracking code. Defaults to auto.

GOSQUARED_SITENAME¶

Set to ‘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¶

在标题上显示链接的元组列表（标题，URL）。

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.

LINKS_WIDGET_NAME¶

Allows override of the name of the links widget. If not specified, defaults to “links”.

SOCIAL_WIDGET_NAME¶

Allows override of the name of the “social” widget. If not specified, defaults to “social”.

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

CSS_FILE = "wide.css"

Logging¶

Sometimes, a long list of warnings may appear during site generation. Finding the meaningful error message in the middle of tons of annoying log output can be quite tricky. In order to filter out redundant log messages, Pelican comes with the LOG_FILTER setting.

LOG_FILTER should be a list of tuples (level, msg), each of them being composed of the logging level (up to warning) and the message to be ignored. Simply populate the list with the log messages you want to hide, and they will be filtered out.

For example:

[(logging.WARN, 'TAG_SAVE_AS is set to False')]

It is possible to filter out messages by a template. Check out source code to obtain a template.

For example:

[(logging.WARN, 'Empty alt attribute for image %s in %s')]

Reading only modified content¶

To speed up the build process, Pelican can optionally read only articles and pages with modified content.

When Pelican is about to read some content source file:

1. The hash or modification time information for the file from a previous build are loaded from a cache file if LOAD_CONTENT_CACHE is True. These files are stored in the CACHE_PATH directory. If the file has no record in the cache file, it is read as usual.

2. The file is checked according to CHECK_MODIFIED_METHOD:

   • If set to 'mtime', the modification time of the file is checked.
   • If set to a name of a function provided by the hashlib module, e.g. 'md5', the file hash is checked.
   • If set to anything else or the necessary information about the file cannot be found in the cache file, the content is read as usual.

3. If the file is considered unchanged, the content data saved in a previous build corresponding to the file is loaded from the cache, and the file is not read.

4. If the file is considered changed, the file is read and the new modification information and the content data are saved to the cache if CACHE_CONTENT is True.

If CONTENT_CACHING_LAYER is set to 'reader' (the default), the raw content and metadata returned by a reader are cached. If this setting is instead set to 'generator', the processed content object is cached. Caching the processed content object may conflict with plugins (as some reading related signals may be skipped) and the WITH_FUTURE_DATES functionality (as the draft status of the cached content objects would not change automatically over time).

Checking modification times is faster than comparing file hashes, but it is not as reliable because mtime information can be lost, e.g., when copying content source files using the cp or rsync commands without the mtime preservation mode (which for rsync can be invoked by passing the --archive flag).

The cache files are Python pickles, so they may not be readable by different versions of Python as the pickle format often changes. If such an error is encountered, it is caught and the cache file is rebuilt automatically in the new format. The cache files will also be rebuilt after the GZIP_CACHE setting has been changed.

The --ignore-cache command-line option is useful when the whole cache needs to be regenerated, such as when making modifications to the settings file that will affect the cached content, or just for debugging purposes. When Pelican runs in autoreload mode, modification of the settings file will make it ignore the cache automatically if AUTORELOAD_IGNORE_CACHE is True.

Note that even when using cached content, all output is always written, so the modification times of the generated *.html files will always change. Therefore, rsync-based uploading may benefit from the --checksum option.

Writing only selected content¶

When only working on a single article or page, or making tweaks to your theme, it is often desirable to generate and review your work as quickly as possible. In such cases, generating and writing the entire site output is often unnecessary. By specifying only the desired files as output paths in the WRITE_SELECTED list, only those files will be written. This list can be also specified on the command line using the --write-selected option, which accepts a comma-separated list of output file paths. By default this list is empty, so all output is written. See Site generation for more details.

Example settings¶

# -*- coding: utf-8 -*-
from __future__ import unicode_literals

AUTHOR = 'Alexis Métaireau'
SITENAME = "Alexis' log"
SITEURL = 'http://blog.notmyidea.org'
TIMEZONE = "Europe/Paris"

# can be useful in development, but set to False when you're ready to publish
RELATIVE_URLS = True

GITHUB_URL = 'http://github.com/ametaireau/'
DISQUS_SITENAME = "blog-notmyidea"
REVERSE_CATEGORY_ORDER = True
LOCALE = "C"
DEFAULT_PAGINATION = 4
DEFAULT_DATE = (2012, 3, 2, 14, 1, 1)

FEED_ALL_RSS = 'feeds/all.rss.xml'
CATEGORY_FEED_RSS = 'feeds/%s.rss.xml'

LINKS = (('Biologeek', 'http://biologeek.org'),
         ('Filyb', "http://filyb.info/"),
         ('Libert-fr', "http://www.libert-fr.com"),
         ('N1k0', "http://prendreuncafe.com/blog/"),
         ('Tarek Ziadé', "http://ziade.org/blog"),
         ('Zubin Mithra', "http://zubin71.wordpress.com/"),)

SOCIAL = (('twitter', 'http://twitter.com/ametaireau'),
          ('lastfm', 'http://lastfm.com/user/akounet'),
          ('github', 'http://github.com/ametaireau'),)

# global metadata to all the contents
DEFAULT_METADATA = {'yeah': 'it is'}

# path-specific metadata
EXTRA_PATH_METADATA = {
    'extra/robots.txt': {'path': 'robots.txt'},
    }

# static paths will be copied without parsing their contents
STATIC_PATHS = [
    'pictures',
    'extra/robots.txt',
    ]

# custom page generated with a jinja2 template
TEMPLATE_PAGES = {'pages/jinja2_template.html': 'jinja2_template.html'}

# code blocks with line numbers
PYGMENTS_RST_OPTIONS = {'linenos': 'table'}

# foobar will not be used, because it's not in caps. All configuration keys
# have to be in caps
foobar = "barbaz"

结构¶

要制作自己的主题，您必须遵循以下结构：

├── static
│   ├── css
│   └── images
└── templates
    ├── archives.html         // to display archives
    ├── period_archives.html  // to display time-period archives
    ├── article.html          // processed for each article
    ├── author.html           // processed for each author
    ├── authors.html          // must list all the authors
    ├── categories.html       // must list all the categories
    ├── category.html         // processed for each category
    ├── index.html            // the index (list all the articles)
    ├── page.html             // processed for each page
    ├── tag.html              // processed for each tag
    └── tags.html             // must list all the tags. Can be a tag cloud.

• static包含将被复制到输出theme文件夹的所有静态资源。上述文件系统布局包括CSS和图像文件夹，但这些只是示例。把你需要的东西放在这里.
• templates包含将用于生成内容的所有模板。上面列出的模板文件是强制性的；您可以添加自己的模板，如果它有助于在创建主题时保持组织。

模板和变量¶

这个想法是使用一个简单的语法，您可以将其嵌入到HTML页面中。本文档描述了哪些模板应该存在于主题中，哪些变量将在生成时传递给每个模板。

所有的模板都可以读取配置文件中的变量,当然,变量必须大写.您可以直接访问它们。

{% for tag, articles in tags|sort %}

{{ article.date|strftime('%d %B %Y') }}

Title: I love Python more than music
Date: 2013-11-06 10:06
Tags: personal, python
Category: Tech
Slug: python-je-l-aime-a-mourir
Author: Francis Cabrel
FacebookImage: http://franciscabrel.com/images/pythonlove.png

<meta property="og:image" content="{{ article.facebookimage }}"/>

对象¶

在模板中可用和有用的详细对象属性。不是所有的属性都列在这里，这是在模板中被认为有用的属性的选择。

Feeds¶

The feed variables changed in 3.0. Each variable now explicitly lists ATOM or RSS in the name. ATOM is still the default. Old themes will need to be updated. Here is a complete list of the feed variables:

FEED_ATOM
FEED_RSS
FEED_ALL_ATOM
FEED_ALL_RSS
CATEGORY_FEED_ATOM
CATEGORY_FEED_RSS
AUTHOR_FEED_ATOM
AUTHOR_FEED_RSS
TAG_FEED_ATOM
TAG_FEED_RSS
TRANSLATION_FEED_ATOM
TRANSLATION_FEED_RSS

Inheritance¶

自3.0版以来，Pelican支持从simple主题继承，因此您可以在自己的主题中重新使用simple主题模板。

如果您的主题的templates /目录中的其中一个强制性文件丢失，将由简单主题中的匹配模板替换。因此，如果simple主题中的模板的HTML结构适合您，则不必从头开始编写新模板。

You can also extend templates from the simple theme in your own themes by using the {% extends %} directive as in the following example:

{% extends "!simple/index.html" %}   <!-- extends the ``index.html`` template from the ``simple`` theme -->

{% extends "index.html" %}   <!-- "regular" extending -->

{% extends "!simple/base.html" %}

{% block head %}
{{ super() }}
   <link rel="stylesheet" type="text/css" href="{{ SITEURL }}/theme/css/style.css" />
{% endblock %}

body {
    font-family : monospace ;
    font-size : 100% ;
    background-color : white ;
    color : #111 ;
    width : 80% ;
    min-width : 400px ;
    min-height : 200px ;
    padding : 1em ;
    margin : 5% 10% ;
    border : thin solid gray ;
    border-radius : 5px ;
    display : block ;
}

a:link    { color : blue ; text-decoration : none ;      }
a:hover   { color : blue ; text-decoration : underline ; }
a:visited { color : blue ;                               }

h1 a { color : inherit !important }
h2 a { color : inherit !important }
h3 a { color : inherit !important }
h4 a { color : inherit !important }
h5 a { color : inherit !important }
h6 a { color : inherit !important }

pre {
    margin : 2em 1em 2em 4em ;
}

#menu li {
    display : inline ;
}

#post-list {
    margin-bottom : 1em ;
    margin-top : 1em ;
}

如何使用插件¶

要加载插件，您必须在设置文件中指定它们。有两种方法可以这样做。第一种方法是使用可调用的路径指定字符串：

PLUGINS = ['package.myplugin',]

或者，另一种方法是导入它们并将它们添加到列表中：

from package import myplugin
PLUGINS = [myplugin,]

如果您的插件不在可以导入的路径中，则可以通过PLUGIN_PATHS设置指定路径列表。如以下示例所示，PLUGIN_PATHS列表中的路径可以是绝对路径，也可以是相对于设置文件的相对路径：

PLUGIN_PATHS = ["plugins", "/srv/pelican/plugins"]
PLUGINS = ["assets", "liquid_tags", "sitemap"]

在哪里可以找到插件¶

我们保留一个独立的插件库，供人们共享和使用。请访问pelican-plugins仓库以获取可用插件的列表。

请注意，尽管我们尽力检查和维护这些插件，但它们由Pelican社区提交，因此可能具有不同级别的支持和互操作性。

如何创建插件¶

插件是基于信号的概念。pelican发送信号，插件订阅这些信号。信号列表在后续章节中定义。

插件的唯一规则是定义一个可调用的register函数，您可以在其中将信号映射到插件逻辑。我们来看一个简单的例子：

from pelican import signals

def test(sender):
    print "%s initialized !!" % sender

def register():
    signals.initialized.connect(test)

信号列表¶

以下列出了当前实施的信号：

方法案例¶

我们最终意识到，创建插件的一些方法最好在文档中共享，所以写在了这里！

from pelican import signals
from pelican.readers import BaseReader

# Create a new reader class, inheriting from the pelican.reader.BaseReader
class NewReader(BaseReader):
    enabled = True  # Yeah, you probably want that :-)

    # The list of file extensions you want this reader to match with.
    # If multiple readers were to use the same extension, the latest will
    # win (so the one you're defining here, most probably).
    file_extensions = ['yeah']

    # You need to have a read method, which takes a filename and returns
    # some content and the associated metadata.
    def read(self, filename):
        metadata = {'title': 'Oh yeah',
                    'category': 'Foo',
                    'date': '2012-12-01'}

        parsed = {}
        for key, value in metadata.items():
            parsed[key] = self.process_metadata(key, value)

        return "Some content", parsed

def add_reader(readers):
    readers.reader_classes['yeah'] = NewReader

# This is how pelican works.
def register():
    signals.readers_init.connect(add_reader)

def get_generators(pelican_object):
    # define a new generator here if you need to
    return MyGenerator

signals.get_generators.connect(get_generators)

描述¶

pelican-themes是一个用于管理pelican主题的命令行工具。

实例¶

$ pelican-themes -l
notmyidea
two-column@
simple
$ pelican-themes --list
notmyidea
two-column@
simple

$ pelican-themes -v -l
/usr/local/lib/python2.6/dist-packages/pelican-2.6.0-py2.6.egg/pelican/themes/notmyidea
/usr/local/lib/python2.6/dist-packages/pelican-2.6.0-py2.6.egg/pelican/themes/two-column (symbolic link to `/home/skami/Dev/Python/pelican-themes/two-column')
/usr/local/lib/python2.6/dist-packages/pelican-2.6.0-py2.6.egg/pelican/themes/simple

# pelican-themes --install ~/Dev/Python/pelican-themes/notmyidea-cms --verbose

# pelican-themes --install ~/Dev/Python/pelican-themes/notmyidea-cms\
                           ~/Dev/Python/pelican-themes/martyalchin \
                           --verbose

# pelican-themes -vi ~/Dev/Python/pelican-themes/two-column

# pelican-themes --remove two-column

# pelican-themes -r martyachin notmyidea-cmd -v

# pelican-themes --symlink ~/Dev/Python/pelican-themes/two-column

$ sudo pelican-themes -s ~/Dev/Python/pelican-themes/two-column
$ pelican ~/Blog/content -o /tmp/out -t two-column
$ firefox /tmp/out/index.html
$ vim ~/Dev/Pelican/pelican-themes/two-column/static/css/main.css
$ pelican ~/Blog/content -o /tmp/out -t two-column
$ cp /tmp/bg.png ~/Dev/Pelican/pelican-themes/two-column/static/img/bg.png
$ pelican ~/Blog/content -o /tmp/out -t two-column
$ vim ~/Dev/Pelican/pelican-themes/two-column/templates/index.html
$ pelican ~/Blog/content -o /tmp/out -t two-column

# pelican-themes --remove notmyidea-cms two-column \
                 --install ~/Dev/Python/pelican-themes/notmyidea-cms-fr \
                 --symlink ~/Dev/Python/pelican-themes/two-column \
                 --verbose

Description¶

pelican-import is a command-line tool for converting articles from other software to reStructuredText or Markdown. The supported import formats are:

• WordPress XML export
• Dotclear export
• Posterous API
• Tumblr API
• RSS/Atom feed

从HTML到reStructuredText或Markdown的转换依赖于Pandoc。对于Dotclear，如果源文章是使用Markdown语法编写的，则不会被转换（因为Pelican也支持Markdown）。

Dependencies¶

pelican-import has some dependencies not required by the rest of Pelican:

• BeautifulSoup4 and lxml, for WordPress and Dotclear import. Can be installed like any other Python package (pip install BeautifulSoup4 lxml).
• Feedparser, for feed import (pip install feedparser).
• Pandoc, see the Pandoc site for installation instructions on your operating system.

Usage¶

pelican-import [-h] [--wpfile] [--dotclear] [--posterous] [--tumblr] [--feed] [-o OUTPUT]
               [-m MARKUP] [--dir-cat] [--dir-page] [--strip-raw] [--disable-slugs]
               [-e EMAIL] [-p PASSWORD] [-b BLOGNAME]
               input|api_token|api_key

Examples¶

For WordPress:

$ pelican-import --wpfile -o ~/output ~/posts.xml

For Dotclear:

$ pelican-import --dotclear -o ~/output ~/backup.txt

for Posterous:

$ pelican-import --posterous -o ~/output --email=<email_address> --password=<password> <api_token>

For Tumblr:

$ pelican-import --tumblr -o ~/output --blogname=<blogname> <api_token>

Tests¶

To test the module, one can use sample files:

• for WordPress: http://wpcandy.com/made/the-sample-post-collection
• for Dotclear: http://media.dotaddict.org/tda/downloads/lorem-backup.txt

最好的交流问题或提建议的形式是什么？¶

请阅读我们的反馈指南.

我能做什么？¶

你可以做的太多了！首先，您可以通过IRC（首选）或问题跟踪器报告任何Pelican建议或问题。If submitting an issue report, please first check the existing issue list (both open and closed) in order to avoid submitting a duplicate issue.

If you want to contribute, please fork the git repository, create a new feature branch, make your changes, and issue a pull request. Someone will review your changes as soon as possible. Please refer to the How to Contribute section for more details.

You can also contribute by creating themes and improving the documentation.

Is the Pelican settings file mandatory?¶

Configuration files are optional and are just an easy way to configure Pelican. For basic operations, it’s possible to specify options while invoking Pelican via the command line. See pelican --help for more information.

Changes to the settings file take no effect¶

When experimenting with different settings (especially the metadata ones) caching may interfere and the changes may not be visible. In such cases, ensure that caching is disabled via LOAD_CONTENT_CACHE = False or use the --ignore-cache command-line switch.

I’m creating my own theme. How do I use Pygments for syntax highlighting?¶

Pygments adds some classes to the generated content. These classes are used by themes to style code syntax highlighting via CSS. Specifically, you can customize the appearance of your syntax highlighting via the .highlight pre class in your theme’s CSS file. To see how various styles can be used to render Django code, for example, use the style selector drop-down at top-right on the Pygments project demo site.

You can use the following example commands to generate a starting CSS file from a Pygments built-in style (in this case, “monokai”) and then copy the generated CSS file to your new theme:

pygmentize -S monokai -f html -a .highlight > pygment.css
cp pygment.css path/to/theme/static/css/

Don’t forget to import your pygment.css file from your main CSS file.

How do I create my own theme?¶

Please refer to Creating themes.

I want to use Markdown, but I got an error.¶

If you try to generate Markdown content without first installing the Markdown library, may see a message that says No valid files found in content. Markdown is not a hard dependency for Pelican, so if you have content in Markdown format, you will need to explicitly install the Markdown library. You can do so by typing the following command, prepending sudo if permissions require it:

pip install markdown

Can I use arbitrary metadata in my templates?¶

Yes. For example, to include a modified date in a Markdown post, one could include the following at the top of the article:

Modified: 2012-08-08

For reStructuredText, this metadata should of course be prefixed with a colon:

:Modified: 2012-08-08

This metadata can then be accessed in templates such as article.html via:

{% if article.modified %}
Last modified: {{ article.modified }}
{% endif %}

If you want to include metadata in templates outside the article context (e.g., base.html), the if statement should instead be:

{% if article and article.modified %}

How do I assign custom templates on a per-page basis?¶

It’s as simple as adding an extra line of metadata to any page or article that you want to have its own template. For example, this is how it would be handled for content in reST format:

:template: template_name

For content in Markdown format:

Template: template_name

Then just make sure your theme contains the relevant template file (e.g. template_name.html).

How can I override the generated URL of a specific page or article?¶

Include url and save_as metadata in any pages or articles that you want to override the generated URL. Here is an example page in reST format:

Override url/save_as page
#########################

:url: override/url/
:save_as: override/url/index.html

With this metadata, the page will be written to override/url/index.html and Pelican will use url override/url/ to link to this page.

How can I use a static page as my home page?¶

The override feature mentioned above can be used to specify a static page as your home page. The following Markdown example could be stored in content/pages/home.md:

Title: Welcome to My Site
URL:
save_as: index.html

Thank you for visiting. Welcome!

If the original blog index is still wanted, it can then be saved in a different location by setting INDEX_SAVE_AS = 'blog_index.html' for the 'index' direct template.

What if I want to disable feed generation?¶

To disable feed generation, all feed settings should be set to None. All but three feed settings already default to None, so if you want to disable all feed generation, you only need to specify the following settings:

FEED_ALL_ATOM = None
CATEGORY_FEED_ATOM = None
TRANSLATION_FEED_ATOM = None
AUTHOR_FEED_ATOM = None
AUTHOR_FEED_RSS = None

The word None should not be surrounded by quotes. Please note that None and '' are not the same thing.

I’m getting a warning about feeds generated without SITEURL being set properly¶

RSS and Atom feeds require all URL links to be absolute. In order to properly generate links in Pelican you will need to set SITEURL to the full path of your site.

Feeds are still generated when this warning is displayed, but links within may be malformed and thus the feed may not validate.

My feeds are broken since I upgraded to Pelican 3.x¶

Starting in 3.0, some of the FEED setting names were changed to more explicitly refer to the Atom feeds they inherently represent (much like the FEED_RSS setting names). Here is an exact list of the renamed settings:

FEED -> FEED_ATOM
TAG_FEED -> TAG_FEED_ATOM
CATEGORY_FEED -> CATEGORY_FEED_ATOM

Starting in 3.1, the new feed FEED_ALL_ATOM has been introduced: this feed will aggregate all posts regardless of their language. This setting generates 'feeds/all.atom.xml' by default and FEED_ATOM now defaults to None. The following feed setting has also been renamed:

TRANSLATION_FEED -> TRANSLATION_FEED_ATOM

Older themes that referenced the old setting names may not link properly. In order to rectify this, please update your theme for compatibility by changing the relevant values in your template files. For an example of complete feed headers and usage please check out the simple theme.

Is Pelican only suitable for blogs?¶

No. Pelican can be easily configured to create and maintain any type of static site. This may require a little customization of your theme and Pelican configuration. For example, if you are building a launch site for your product and do not need tags on your site, you could remove the relevant HTML code from your theme. You can also disable generation of tag-related pages via:

TAGS_SAVE_AS = ''
TAG_SAVE_AS = ''

Why does Pelican always write all HTML files even with content caching enabled?¶

In order to reliably determine whether the HTML output is different before writing it, a large part of the generation environment including the template contexts, imported plugins, etc. would have to be saved and compared, at least in the form of a hash (which would require special handling of unhashable types), because of all the possible combinations of plugins, pagination, etc. which may change in many different ways. This would require a lot more processing time and memory and storage space. Simply writing the files each time is a lot faster and a lot more reliable.

However, this means that the modification time of the files changes every time, so a rsync based upload will transfer them even if their content hasn’t changed. A simple solution is to make rsync use the --checksum option, which will make it compare the file checksums in a much faster way than Pelican would.

When only several specific output files are of interest (e.g. when working on some specific page or the theme templates), the WRITE_SELECTED option may help, see Writing only selected content.

How to process only a subset of all articles?¶

It is often useful to process only e.g. 10 articles for debugging purposes. This can be achieved by explicitly specifying only the filenames of those articles in ARTICLE_PATHS. A list of such filenames could be found using a command similar to cd content; find -name '*.md' | head -n 10.

My tag-cloud is missing/broken since I upgraded Pelican¶

In an ongoing effort to steamline Pelican, tag_cloud generation has been moved out of the pelican core and into a separate plugin. See the Plugins documentation further information about the Pelican plugin system.

Since I upgraded Pelican my pages are no longer rendered¶

Pages were available to themes as lowercase pages and uppercase PAGES. To bring this inline with the Templates and variables section, PAGES has been removed. This is quickly resolved by updating your theme to iterate over pages instead of PAGES. Just replace:

{% for pg in PAGES %}

with something like:

{% for pg in pages %}

How can I stop Pelican from trying to parse my static files as content?¶

Pelican’s article and page generators run before it’s static generator. That means if you use a setup similar to the default configuration, where a static source directory is defined inside a *_PATHS setting, all files that have a valid content file ending (.html, .rst, .md, ...) will be treated as articles or pages before they get treated as static files.

To circumvent this issue either use the appropriate *_EXCLUDES setting or disable the offending reader via READERS if you don’t need it.

自定义404页¶

当浏览器请求Web服务器找不到的资源时，Web服务器通常会显示一个通用的“文件未找到”（404）错误页面，这个页面可能是光秃秃的而不雅观的。提供与您网站主题相匹配的错误页面的一种方法是创建自定义404页面（不是一篇文章），例如存储在content/pages/404.md：

Title: Not Found
Status: hidden
Save_as: 404.html

The requested item could not be located. Perhaps you might want to check
the [Archives](/archives.html)?

下一步是配置您的Web服务器来显示此自定义页面，而不是其默认的404页面。对于Nginx，将以下内容添加到配置文件的location块中：

error_page 404 /404.html;

对于Apache：

ErrorDocument 404 /404.html

对于Amazon S3，首先导航到您的AWS cosole上的桶设置中的Static Site Hosting菜单。从那里：

Error Document: 404.html

发布到GitHub ¶

GitHub页面提供了一种简单方便的发布pelican网站的方法。两种类型的GitHub页面：项目页面和用户页面。鹈鹕网站可以作为项目页面和用户页面一起发布。

$ pelican content -o output -s pelicanconf.py
$ ghp-import output
$ git push origin gh-pages

$ pelican content -o output -s pelicanconf.py
$ ghp-import output
$ git push git@github.com:elemoine/elemoine.github.io.git gh-pages:master

pelican content -o output -s pelicanconf.py && ghp-import output && git push origin gh-pages

STATIC_PATHS = ['images', 'extra/CNAME']
EXTRA_PATH_METADATA = {'extra/CNAME': {'path': 'CNAME'},}

如何添加YouTube或Vimeo视频¶

最简单的方法是将来自这些网站的视频的嵌入代码直接粘贴到源内容中。

或者，您还可以使用像liquid_tags，pelican_youtube或pelican_vimeo之类的Pelican插件将视频嵌入到您的内容中。

此外，标记语言（如reST和Markdown）具有插件，可让您将视频嵌入到标记中。对于Markdown，您可以使用reST视频指令作为reST或mdx_video插件。

提交问题¶

• 在您提出问题之前，首先尝试请求帮助。
• 如果确定提出问题，请首先检查现有问题，包括已关闭的问题。

如何获得帮助¶

在您寻求帮助之前，请确保您执行以下操作：

1. 仔细阅读文档。如果匆忙，至少使用文档页面左上方提供的搜索字段。确保您阅读了您正在使用的Pelican版本的文档。
2. 使用搜索引擎（例如，DuckDuckGo，Google）来搜索您的问题的解决方案。有人可能已经找到了解决方案，也许是以插件或特定的设置组合的形式。
3. 尝试在干净的环境中重现问题，确保您使用：