设置¶

可以通过命令行给Pelican传入配置文件：

pelican content -s path/to/your/pelicanconf.py

如果使用的是 pelican-quickstart 命令，默认的主配置文件时 pelicanconf.py 。

通过 -e / --extra-settings 选项，可以直接指定一些配置来覆盖配置文件中的设置。需要注意的是，选项值必须时JSON格式的：

pelican content -e SITENAME='"A site"' READERS='{"html": null}' CACHE_CONTENT=true

可以在命令中使用环境变量，但是需要正确地进行转义：

pelican content -e API_KEY=''\"$API_KEY\"''

备注

在尝试不同的设置（特别是尝试元数据）时，受缓存的干扰，对设置的更改可能不会生效。在这种情况下，指定 LOAD_CONTENT_CACHE = False 设置或 --ignore-cache 命令行选项即可。

设置以Python模块（一个文件）的形式。示例配置文件可供您参考。

要查看当前环境下的配置，同时查看默认的或是自定义的配置值，执行下面的命令（在后面以参数的形式添加一个或多个指定的配置名称，可以单独查看指定的配置项）:

pelican --print-settings

所有设置的键（设置中的变量名）都必须是大写的，否则会被无视。配置值可能是数值（5、20等）、布尔值（True、False、None等）、字典或者元组。这些值应该以Python值的形式存在，不需要用引号引起来。除此之外的其他配置值（例如字符串）必须用引号引起来。

除非另有指定，设置中指定的路径可以是绝对路径，也可以是相对于配置文件的相对路径。设置中配置的东西会传递到网站模板中，这使得可以在配置文件中添加在整个站点中都能使用的内容。

下面是Pelican设置项的列表：

基础设置¶

USE_FOLDER_AS_CATEGORY¶: 当您没有在推文中指定元数据categroy时，若本项设置设为了 True ，并且文章也是通过子文件夹进行分类管理的，那么这些子文件夹的名称就会作为发布内容的分类。若本项设为了 False ，会使用配置项 DEFAULT_CATEGORY 作为默认分类。本项设置默认为 True 。

DEFAULT_CATEGORY¶: The default category to fall back on. The default is "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¶: A dictionary of custom Jinja2 environment variables you want to use. This also includes a list of extensions you may want to include. See Jinja Environment documentation. The default is {"extensions": [], "trim_blocks": True, "lstrip_blocks": True}.

JINJA_FILTERS¶

一个字典，存放自定义的Jinja2过滤器。此字典中应该是过滤器名称到过滤器函数的映射。

例子：

import sys
sys.path.append("to/your/path")

from custom_filter import urlencode_filter
JINJA_FILTERS = {"urlencode": urlencode_filter}

详见： Jinja自定义过滤器文档。本项设置默认为 {} 。

JINJA_GLOBALS¶: 一个字典，可以将自定义对象映射到Jinja2的全局环境命名空间中。字典中应该是全局名称到全局变量/函数的映射。详见： Jinja全局命名空间文档。本项设置默认为 {} 。

JINJA_TESTS¶: 一个字典，自定义了要使用的Jinja测试。字典中应该是测试名到测试函数的映射。详见： Jinja自定义测试文档。本项设置默认为 {} 。

LOG_FILTER¶

一个以元组为元素的列表，元组中包含日志等级（最高到 warning）和要忽略的消息。

例子：

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

默认为 [] 。

READERS¶

一个字典，记录了文件扩展名到Reader类的映射。可以据此让Pelican按照指定规则处理或忽略某些文件。

例如，下面的配置可以让Pelican忽略 .html的文件不处理：

READERS = {"html": None}

为扩展名为 foo 的文件添加自定义的reader：

READERS = {"foo": FooReader}

默认为 {} 。

IGNORE_FILES¶

A list of Unix glob patterns. Files and directories matching any of these patterns or any of the commonly hidden files and directories set by watchfiles.DefaultFilter will be ignored by the processor. For example, the default ["**/.*"] will ignore "hidden" files and directories, and ["__pycache__"] would ignore Python 3's bytecode caches.

请参阅 watchfiles文档以获取 watchfiles.DefaultFilter 中设置常见隐藏文件的完整列表

The default is ["**/.*"].

MARKDOWN¶

对Markdown处理器的额外配置。可以参考Python Markdown文档的选项章节，查看可用选项的完整列表。其中的 extensions_configs 选项会用于自动计算 extensions 选项。

默认值为：

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

备注

配置文件中的字典会覆盖默认设置。

OUTPUT_PATH¶

输出生成文件的位置。此项配置应该和web服务器虚拟主机的根目录有关。

The default is "output".

PATH¶: Path to content directory to be processed by Pelican. If undefined, and content path is not specified via an argument to the pelican command, Pelican will default to ".", the current working directory.

PAGE_PATHS¶: A list of directories and files to look at for pages, relative to PATH. The default is ["pages"].

PAGE_EXCLUDES¶: 除了 ARTICLE_PATHS 中的文件不会被视为页面外，此选项中也可指定不被视为页面的文件目录。本项配置默认为 [] 。

ARTICLE_PATHS¶: A list of directories and files to look at for articles, relative to PATH. The default is [""].

ARTICLE_EXCLUDES¶: 除了 PAGE_PATHS 中的文件不会被视为文章外，此选项中也可指定不被视为文章的文件目录。本项配置默认为 [] 。

OUTPUT_SOURCES¶: 如果你想要将文章和页面以源格式（例如Markdown或reStructuredText）复制一份到 OUTPUT_PATH 目录中，就将此项设为True。本项配置默认为 False 。

OUTPUT_SOURCES_EXTENSION¶: Controls the extension that will be used by the SourcesGenerator. Defaults to .text. If not a valid string the default value will be used. The default is ".text".

PLUGINS¶: 要加载的插件列表。详见插件。本项配置默认为 None 。

PLUGIN_PATHS¶: 查找插件的目录列表。详见插件。本项配置默认为 [] 。

SITENAME¶: Your site's name. The default is "A Pelican Blog".

SITEURL¶

Base URL of your web site. Not defined by default, so it is best to specify your SITEURL; if you do not, feeds will not be generated with properly-formed URLs. If your site is available via HTTPS, this setting should begin with https:// — otherwise use http://. Then append your domain, with no trailing slash at the end. Example: SITEURL = "https://example.com"

The default is "", the blank string.

STATIC_PATHS¶: A list of directories (relative to PATH) in which to look for static files. Such files will be copied to the output directory without modification. Articles, pages, and other content source files will normally be skipped, so it is safe for a directory to appear both here and in PAGE_PATHS or ARTICLE_PATHS. Pelican's default settings include the "images" directory here. The default is ["images"].

STATIC_EXCLUDES¶: 此选项列表中的目录都会在搜索静态文件时排除在外。本项配置默认为 [] 。

STATIC_EXCLUDE_SOURCES¶: 如果此选项设为False， STATIC_PATHS 中的内容源文件将不会被忽略，也会像静态文件一样被原封不动地拷贝。此项设置是为了给3.5版本前的Pelican进行向后兼容的。若某个目录同时出现在了 STATIC_PATHS 和 ARTICLE_PATHS 中，或 STATIC_PATHS 和 PAGE_PATHS 中时才会生效。如果你是想将站点的源文件发布出去的话，请考虑使用 OUTPUT_SOURCES 。本项配置默认为 True 。

STATIC_CREATE_LINKS¶: 为静态文件创建链接而不是复制文件本身。如果内容和输出目录位于同一设备上，则创建硬链接；如果输出目录位于不同的文件系统上，则回退至符号链接。若创建了符号链接，使用rsync上传网站时需要添加-L或--copy-links选项。本项配置默认为 False 。

STATIC_CHECK_IF_MODIFIED¶: 当此项设为 True 且 STATIC_CREATE_LINKS 设为 False 时才会生效，此时会比较mtime，只有在当前文件更新时才会执行拷贝。本项配置默认为 False 。

TYPOGRIFY¶: 若此项设置为True，一些显示上的改进将通过 Typogrify 库合并到生成的HTML中。可以通过 python -m pip install typogrify 进行安装。本项配置默认为 False 。

TYPOGRIFY_IGNORE_TAGS¶: 指定Typogrify要忽略的标签列表。默认情况下，Typogrify将忽略 pre 和 code 标签此项特性需要安装高于2.0.4版本的Typogrify。。本项配置默认为 [] 。

TYPOGRIFY_OMIT_FILTERS¶: A list of Typogrify filters to skip. Allowed values are: "amp", "smartypants", "caps", "initial_quotes", "widont". By default, no filter is omitted (in other words, all filters get applied). This setting requires that Typogrify version 2.1.0 or later is installed. The default is [].

TYPOGRIFY_DASHES¶: This setting controls how Typogrify sets up the Smartypants filter to interpret multiple dash/hyphen/minus characters. A single ASCII dash character (-) is always rendered as a hyphen. The default setting does not handle en-dashes and converts double-hyphens into em-dashes. The oldschool setting renders both en-dashes and em-dashes when it sees two (--) and three (---) hyphen characters, respectively. The oldschool_inverted setting turns two hyphens into an em-dash and three hyphens into an en-dash. The default is "default".

SUMMARY_MAX_LENGTH¶: 当未给文章或页面书写摘要时，会自动创建摘要，此设置指定了默认创建摘要的长度（以字/词为单位）。若将此项设为 None ，摘要会和原始内容一模一样。本项配置默认为 50 。

SUMMARY_MAX_PARAGRAPHS¶: 当未给文章或页面书写摘要时，会自动创建摘要。此设置指定了默认创建摘要的段落数，即将正文的前N段视为摘要。若将此项设为 None ，摘要会和原始内容一模一样，但具体还会遵循 SUMMARY_MAX_LENGTH 。本项配置默认为 None 。

SUMMARY_END_SUFFIX¶: When creating a short summary of an article and the result was truncated to match the required word length, this will be used as the truncation suffix. The default is "…".

WITH_FUTURE_DATES¶: 若此项设为False，带了未来日期的文章或页面的状态都会设为 draft 。相关注意事项详见 Reading Only Modified Content 。本项配置默认为 True 。

INTRASITE_LINK_REGEX¶: Regular expression that is used to parse internal links. Default syntax when linking to internal files, tags, etc., is to enclose the identifier, say filename, in {} or ||. Identifier between { and } goes into the what capturing group. For details see 内部链接. The default is "[{|](?P<what>.*?)[|}]".

PYGMENTS_RST_OPTIONS¶: reStructuredText代码块的默认Pygments设置列表。请参阅语法高亮查看支持选项列表。本项配置默认为 {} 。

CACHE_CONTENT¶: 若设为 True ，会将内容保存在缓存中。有关缓存请参阅 Reading Only Modified Content 。本项配置默认为 False 。

CONTENT_CACHING_LAYER¶: If set to "reader", save only the raw content and metadata returned by readers. If set to "generator", save processed content objects. The default is "reader".

CACHE_PATH¶: Directory in which to store cache files. The default is "cache".

GZIP_CACHE¶: 若设为 True ，则使用gzip对缓存文件进行解压缩。本项配置默认为 True 。

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.

The default is "mtime".

LOAD_CONTENT_CACHE¶: 若设为 True ，则会从缓存中加载未修改的内容。本项配置默认为 False 。

FORMATTED_FIELDS¶: A list of metadata fields containing reST/Markdown content to be parsed and translated to HTML. The default is ["summary"].

PORT¶: 使用--listen运行pelican时，会在此选项指定的TCP端口上以HTTP提供内容。本项配置默认为 8000 。

BIND¶: The IP to which to bind the HTTP server. The default is "127.0.0.1".

URL设置¶

首先要知道的是，URL格式有两种形式： 相对URL 、 绝对URL 。相对URL在本地测试时往往比较有用，而绝对URL在发布时往往是比较有效可靠的。要同时支持两种URL形式，可以在本地开发和发布环境中使用两份不同的配置文件。执行脚本 pelican-quickstart 时，就会为本地开发和发布环境分别生成一份配置文件，此脚本在安装Pelican 一节中有详细描述。

URL和文件存储位置都是可以自定义的， *_URL 和 *_SAVE_AS 变量使用Python风格的格式化字符串。你可以利用一些变量将文章放在诸如 {slug}/index.html 的位置，并且可以以 {slug} 的形式进行链接，如此可以让URL更加简洁（详见下面的例子）。这些设置可以让你灵活地将文章和页面放在任何你想要的地方。

备注

如果 *_SAVE_AS 中包含了不在 *_URL 中的父目录，会导致Pelican在少数情况下（例如使用 {attach} 语法时）产生不确定的URL。

若不希望有这种灵活性，而是希望生成的输出路径保留源内容路径的层次结构，可以尝试以下设置：

PATH_METADATA = r"(?P<path_no_ext>.*)\..*"
ARTICLE_URL = ARTICLE_SAVE_AS = PAGE_URL = PAGE_SAVE_AS = "{path_no_ext}.html"

否则，可以在URL相关设置中可以使用下面的这些元数据属性：

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"
PAGE_URL = "pages/{slug}/"
PAGE_SAVE_AS = "pages/{slug}/index.html"

上面的设置会将你的文章以类似于 /posts/2011/Aug/07/sample-post/index.html 的形式存储，页面则以 /pages/about/index.html 的形式存储，对应的URL分别为 /posts/2011/Aug/07/sample-post/ 与 /pages/about/ 。

备注

如果指定了 datetime 指令，会使用输入文件的日期元数据进行替换。若没有指定日期，Pelican会根据文件的 mtime 时间戳替换之。更多信息可以参考 Python datetime文档。

RELATIVE_URLS¶: 定义Pelican是否使用文档间的相对URL。请只在开发或测试时将此项设为 True ，并且确保你已经明白此项设置对链接与feed的影响。（译者注：当此项为True时，网页之间的链接会使用相对路径表达，例如 ../my-article.html ）。本项配置默认为 False 。

ARTICLE_URL¶: The URL to refer to an article. The default is "{slug}.html".

ARTICLE_SAVE_AS¶: The place where we will save an article. The default is "{slug}.html".

ARTICLE_LANG_URL¶: The URL to refer to an article which doesn't use the default language. The default is "{slug}-{lang}.html".

ARTICLE_LANG_SAVE_AS¶: The place where we will save an article which doesn't use the default language. The default is "{slug}-{lang}.html".

DRAFT_URL¶: The URL to refer to an article draft. The default is "drafts/{slug}.html".

DRAFT_SAVE_AS¶: The place where we will save an article draft. The default is "drafts/{slug}.html".

DRAFT_LANG_URL¶: The URL to refer to an article draft which doesn't use the default language. The default is "drafts/{slug}-{lang}.html".

DRAFT_LANG_SAVE_AS¶: The place where we will save an article draft which doesn't use the default language. The default is "drafts/{slug}-{lang}.html".

PAGE_URL¶: The URL we will use to link to a page. The default is "pages/{slug}.html".

PAGE_SAVE_AS¶: 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. The default is "pages/{slug}.html".

PAGE_LANG_URL¶: The URL we will use to link to a page which doesn't use the default language. The default is "pages/{slug}-{lang}.html".

PAGE_LANG_SAVE_AS¶: The location we will save the page which doesn't use the default language. The default is "pages/{slug}-{lang}.html".

DRAFT_PAGE_URL¶: The URL used to link to a page draft. The default is "drafts/pages/{slug}.html".

DRAFT_PAGE_SAVE_AS¶: The actual location a page draft is saved at. The default is "drafts/pages/{slug}.html".

DRAFT_PAGE_LANG_URL¶: The URL used to link to a page draft which doesn't use the default language. The default is "drafts/pages/{slug}-{lang}.html".

DRAFT_PAGE_LANG_SAVE_AS¶: The actual location a page draft which doesn't use the default language is saved at. The default is "drafts/pages/{slug}-{lang}.html".

AUTHOR_URL¶: The URL to use for an author. The default is "author/{slug}.html".

AUTHOR_SAVE_AS¶: The location to save an author. The default is "author/{slug}.html".

CATEGORY_URL¶: The URL to use for a category. The default is "category/{slug}.html".

CATEGORY_SAVE_AS¶: The location to save a category. The default is "category/{slug}.html".

TAG_URL¶: The URL to use for a tag. The default is "tag/{slug}.html".

TAG_SAVE_AS¶: The location to save the tag page. The default is "tag/{slug}.html".

备注

If you do not want one or more of the default pages to be created (e.g., you are the only author on your site and thus do not need an Authors page), set the corresponding *_SAVE_AS setting to "" to prevent the relevant page from being generated.

可选的，Pelican可以为帖子创建每年、每月或是每日的归档。除非你为各自的 *_SAVE_AS 设置了格式化字符串，否则这些归档在默认情况下是关闭的。按时间进行归档更直观地符合web URL的层次模型，也可以让读者更容易按时间顺序浏览帖子。

例如：

YEAR_ARCHIVE_SAVE_AS = "posts/{date:%Y}/index.html"
YEAR_ARCHIVE_URL = "posts/{date:%Y}/"
MONTH_ARCHIVE_SAVE_AS = "posts/{date:%Y}/{date:%b}/index.html"
MONTH_ARCHIVE_URL = "posts/{date:%Y}/{date:%b}/"

例如若使用了上面的设置，Pelican会创建按年的归档（例如 posts/2011/index.html ），以及按月的归档（例如 posts/2011/Aug/index.html ）。这两个页面分别通过 posts/2011/ 和 posts/2011/Aug/ 进行访问。

备注

当路径设置为以 index.html 结尾时，归档的体验会非常好。读者可以删除URL中的一部分以到达合适时间段的归档，而不需要指定某一个页面的名称。

YEAR_ARCHIVE_SAVE_AS¶: The location to save per-year archives of your posts. The default is "", i.e. this is disabled by default.

YEAR_ARCHIVE_URL¶: The URL to use for per-year archives of your posts. You should set this if you enable per-year archives. The default is "", i.e. this is disabled by default.

MONTH_ARCHIVE_SAVE_AS¶: The location to save per-month archives of your posts. The default is "", i.e. this is disabled by default.

MONTH_ARCHIVE_URL¶: The URL to use for per-month archives of your posts. You should set this if you enable per-month archives. The default is "", i.e. this is disabled by default.

DAY_ARCHIVE_SAVE_AS¶: The location to save per-day archives of your posts. The default is "", i.e. this is disabled by default.

DAY_ARCHIVE_URL¶: The URL to use for per-day archives of your posts. You should set this if you enable per-day archives. The default is "", i.e. this is disabled by default.

DIRECT_TEMPLATES 的工作方式与上面提到的有点不同，在其中可以使用一些特别的直接模板，并且仅在 *_SAVE_AS 设置中可用。

ARCHIVES_SAVE_AS¶: The location to save the article archives page. The default is "archives.html".

AUTHORS_SAVE_AS¶: The location to save the author list. The default is "authors.html".

CATEGORIES_SAVE_AS¶: The location to save the category list. The default is "categories.html".

TAGS_SAVE_AS¶: The location to save the tag list. The default is "tags.html".

INDEX_SAVE_AS¶: The location to save the list of all articles. The default is "index.html".

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

SLUGIFY_SOURCE¶: Specifies from where you want the slug to be automatically generated. Can be set to title to use the "Title:" metadata tag or basename to use the article's file name when creating the slug. The default is "title".

SLUGIFY_USE_UNICODE¶: 指定是否允许在slug中使用Unicode字符。若设为 True ，自动生成的slug中会保留Unicode字符；否则Unicode字符会使用含义相同的ASCII替换。本项配置默认为 False 。

SLUGIFY_PRESERVE_CASE¶: 指定是否保留slug中的大写字母。若设为 True ，则会原样保留 SLUGIFY_SOURCE 中的大写字母。本项配置默认为 False 。

SLUG_REGEX_SUBSTITUTIONS¶

指定生成文章和页面slug时要进行的正则表达式替换。指定的是一对对 (from, to) （from为要替换的内容，to为替换进去的内容），列表中的各对替换规则是按序执行且忽略大小写的。默认的替换会删除非字母非数字的字符并将内部空格替换为连字符。除此之外，slug会将所有字符转换为小写ASCII字符，并删除所有前导和末尾空格。这有利于现有URL的向后兼容。本项配置默认如下：

[
    (r"[^\w\s-]", ""),   # remove non-alphabetical/whitespace/"-" chars
    (r"(?u)\A\s*", ""),  # strip leading whitespace
    (r"(?u)\s*\Z", ""),  # strip trailing whitespace
    (r"[-\s]+", "-"),    # reduce multiple whitespace or "-" to single "-"
]

AUTHOR_REGEX_SUBSTITUTIONS¶: 针对作者slug的正则替换。默认等于 SLUG_REGEX_SUBSTITUTIONS 。

CATEGORY_REGEX_SUBSTITUTIONS¶: 针对分类slug的正则替换。默认等于 SLUG_REGEX_SUBSTITUTIONS 。

TAG_REGEX_SUBSTITUTIONS¶: 针对标签slug的正则替换。默认等于 SLUG_REGEX_SUBSTITUTIONS 。

日期与时间¶

TIMEZONE¶

日期信息中使用的时区，会用于生成Atom和RSS feeds。（无默认值，必须手动设置指定）

若没有定义时区，会直接使用UTC时区。这意味着当你的时区不等于UTC时，生成的Atom和RSS feeds中会包含错误的日期信息。

在之前的版本中，这一项设置并不是强制的，因此Pelican会在未设置时区时提出警告。

有效的时区设置值可以在维基百科页中查看。

DEFAULT_DATE¶: 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. The default is None.

DEFAULT_DATE_FORMAT¶: The default date format you want to use. The default is "%a %d %B %Y", e.g. "Mon 06 April 2026".

DATE_FORMATS¶

若需要管理多种语言，可以在这里针对不同语言设置不同的日期格式。

如果 DATE_FORMATS 没有设置过，Pelican会使用 DEFAULT_DATE_FORMAT 。如果要为不同语言设置不同如期格式，可以在此设置项字典中指定，键为语言名称（对应于帖子内容元数据中的 lang ），值为日期格式字符串。

除了 Python datetime文档中列出的标准C89 strftime格式代码之外，可以通过在 % 和格式字符之间添加 - 来删除日期中的前导零。例如 %d/%m/%Y 对应输出 01/01/2014 ，而 %-d/%-m/%Y 对应输出 1/1/2014 。

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

你还能够通过将元组 (locale, format) 作为值，来为每种语言指定地区，此处设置的地区会覆盖 LOCALE 设置：

# 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¶

设置地区。可以同时指定多个地区，也可以使用字符串指定单个地区。当设置了多个地区时，会一个个尝试直到某一个可以使用。

通过设置地区进一步控制日期格式：

LOCALE = [
    "usa", "jpn",      # On Windows
    "en_US", "ja_JP"   # On Unix/Linux
]

要查看可用的地区列表，可以参看 Windows上的地区；若使用的时Unix/Linux系统，使用 locale -a 命令即可，有关该命令的更多信息可以参阅手册 locale(1) 。本项配置默认与系统locale保持一致。

模板页面¶

TEMPLATE_PAGES¶

一些映射关系，指出了会和博客一起渲染的模板页面。

如果你想要生成除了博客之外的自定义页面，你可以指出任何Jinja2的模板文件，需要同时指出源文件路径和生成文件的路径。

例如，如果你的博客有三个静态页面——书籍列表、你的简历、以及一个联系我们页面，你可这么配置：

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

默认为 {} 。

TEMPLATE_EXTENSIONS¶: The extensions to use when looking up template files from template names. The default is [".html"].

DIRECT_TEMPLATES¶

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., category and tag index pages). If the author, category and tag collections are not needed, set DIRECT_TEMPLATES = ["index", "archives"]

DIRECT_TEMPLATES 会在 THEME_TEMPLATES_OVERRIDES 的路径中搜索。

The default is ["index", "tags", "categories", "authors", "archives"].

元数据¶

AUTHOR¶: 默认作者（通常是你自己）。本项配置默认为 None ，此时会删除作者名一行。

DEFAULT_METADATA¶: 应用于所有文章和页面的默认元数据。本项配置默认为 {} 。

FILENAME_METADATA¶

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 is r"(?P<date>\d{4}-\d{2}-\d{2}).*" and will only extract the date from the filename.

For example, if your source file were titled 2026-04-30_blog-article.md, you could extract both the date and the slug:

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

giving you a date of April 30, 2026 and a slug of blog-article.

See also SLUGIFY_SOURCE. The default is r"(?P<date>\d{4}-\d{2}-\d{2}).*", i.e. it assumed your filenames start with an ISO-style date, e.g. 2026-04-30.

订阅源设置¶

默认情况下，Pelican会使用Atom订阅源。但如果你愿意的话，也可以使用RSS。

Pelican会生成分类的feed，也会为所有文章生成，但默认并不会为标签生成feed，要生成标签feed，可以使用 TAG_FEED_ATOM 和 TAG_FEED_RSS 设置：

FEED_DOMAIN¶: 指定要附加到订阅源URL前面的域名。因为订阅源URL应该是绝对的，所以强烈推荐定义此设置项（例如 https://feeds.example.com ）。本项配置默认为 SITEURL 。

FEED_ATOM¶: 指定Atom订阅源的存储位置。本项配置默认为 None ，即不使用Atom订阅源。

FEED_ATOM_URL¶: Atom订阅源的相对URL。如果未设置此项，会将 FEED_ATOM 同时用于存储位置和URL。本项配置默认为 None 。

FEED_RSS¶: RSS订阅源的存储位置。本项配置默认为 None ，即不使用RSS订阅源。

FEED_RSS_URL¶: RSS订阅源的相对URL。如果未设置此项，会将 FEED_RSS 同时用于存储位置和URL。本项配置默认为 None 。

FEED_ALL_ATOM¶: The location to save the all-posts Atom feed: this feed will contain all posts regardless of their language. The default is "feeds/all.atom.xml".

FEED_ALL_ATOM_URL¶: all-posts Atom订阅源的相对URL。如果未设置此项，会将 FEED_ALL_ATOM 同时用于存储位置和URL。本项配置默认为 None 。

FEED_ALL_RSS¶: 存储all-posts RSS订阅源的文件位置：其中会包含所有语言的帖子。本项配置默认为 None ，即不使用all-posts RSS订阅源。

FEED_ALL_RSS_URL¶: all-posts RSS订阅源的相对URL。如果未设置此项，会将 FEED_ALL_RSS 同时用于存储位置和URL。本项配置默认为 None 。

CATEGORY_FEED_ATOM¶: The location to save the category Atom feeds. [2] The default is "feeds/{slug}.atom.xml".

CATEGORY_FEED_ATOM_URL¶: category Atom订阅源的相对URL，其中包含 {slug} 。 [2] 如果未设置，会将 CATEGORY_FEED_ATOM 同时用于存储位置和URL。本项配置默认为 None 。

CATEGORY_FEED_RSS¶: category RSS订阅源的存储位置，其中包含 {slug} 。 [2] 本项配置默认为 None ，即不使用RSS订阅源。

CATEGORY_FEED_RSS_URL¶: category RSS订阅源的相对URL，其中包含 {slug} 。 [2] 如果未设置，会将 CATEGORY_FEED_RSS 同时用于存储位置和URL。本项配置默认为 None 。

AUTHOR_FEED_ATOM¶: The location to save the author Atom feeds. [2] The default is "feeds/{slug}.atom.xml".

AUTHOR_FEED_ATOM_URL¶: author Atom订阅源的相对URL，其中包含 {slug} 。 [2] 如果未设置，会将 AUTHOR_FEED_ATOM 同时用于存储位置和URL。本项配置默认为 None ，即不使用。

AUTHOR_FEED_RSS¶: The location to save the author RSS feeds. [2] The default is "feeds/{slug}.rss.xml".

AUTHOR_FEED_RSS_URL¶: author RSS订阅源的相对URL，其中包含 {slug} 。 [2] 如果未设置，会将 AUTHOR_FEED_RSS 同时用于存储位置和URL。本项配置默认为 None 。

TAG_FEED_ATOM¶: tag Atom订阅源的存储位置，其中包含 {slug} 。 [2] 本项配置默认为 None ，即不使用tag feed。

TAG_FEED_ATOM_URL¶: tag Atom订阅源的相对URL，其中包含 {slug} 。 [2] 本项配置默认为 None 。

TAG_FEED_RSS¶: tag RSS订阅源的相对URL，其中包含 {slug} 。如果未设置，会将 TAG_FEED_RSS 同时用于存储位置和URL。本项配置默认为 None ，即不使用tag feed。

FEED_MAX_ITEMS¶: Maximum number of items allowed in a feed. Setting to None will cause the feed to contains every article. The default is 100.

RSS_FEED_SUMMARY_ONLY¶: 仅在RSS订阅源的 description 标签中包含项目摘要。若设为 False ，则将包含完整内容。此项设置不会影响Atom feed，只针对RSS feed。本项配置默认为 True 。

FEED_APPEND_REF¶: 若设为 True ，会将 ?ref=feed 附到生成的链接中，以便追踪引用。本项配置默认为 False 。

若你不想要生成某些订阅源，将对应变量设为 None 即可。

分页¶

默认情况下，Pelican会把所有文章以简短描述的形式展示在首页上。虽然这对中小型网站效果不错，但对于拥有大量文章的网站来说可能需要将此列表进行分页。

你可以使用下面的设置来配置分页。

DEFAULT_ORPHANS¶: 最后一页允许的最小文章数。当不希望最后一页仅包含少数文章时，请使用此选项。（译者注：当最后一页达不到此最小文章数时，会被合并到前一页）本项配置默认为 0 。

DEFAULT_PAGINATION¶: 一个页面上包含的最大文章数，不包括孤立文章（译者注：当发生上一条设置选项中提到的合并时，最后一页显然会超过此最大文章数）。设为False会禁用分页。本项配置默认为 False 。

PAGINATED_TEMPLATES¶: The templates to use pagination with, and the number of articles to include on a page. If this value is None, it defaults to DEFAULT_PAGINATION. The default is {"index": None, "tag": None, "category": None, "author": None}.

PAGINATION_PATTERNS¶

一组匹配模式，用于高级分页输出。本项配置默认如下：

(
    (1, "{name}{extension}", "{name}{extension}"),
    (2, "{name}{number}{extension}", "{name}{number}{extension}""),
)

使用分页模式¶

默认情况下，连续页面的URL会如此编码：第一页为 .../foo.html ，后一页为 .../foo2.html 。PAGINATION_PATTERNS 就是用于修改这个编页规则的，其中是一些三元组：

(minimum_page, page_url, page_save_as,)

在 page_url 和 page_save_as 中，你可以使用很多变量。对于不同的页面类型， {url} 和 {save_as} 对应于其 *_URL 和 *_SAVE_AS 配置项的计算值（例如 ARTICLE_SAVE_AS ）。假设 {save_as} == foo/bar.html ，那么此时 {name} == foo/bar 、{extension} == .html 。另外， {base_name} 和 {name} 相同，只不过会截去末尾的 /index （如果有的话）。 {number} 则等于页码。（译者注： minimum_page 意味到达该页面数后开始使用此条规则）

举个例子，如果你想要保持第一面保持不变，但后续页面都以 .../page/2/ 的形式出现，你可以如此设置 PAGINATION_PATTERNS ：

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

如果你想指定最后一面制定规则，将 minimum_page 的值设为 -1 即可：

(-1, "{base_name}/last/", "{base_name}/last/index.html"),

翻译¶

Pelican为文章翻译提供了展示方法。详见创作内容。

DEFAULT_LANG¶: The default language to use. The default is "en".

ARTICLE_TRANSLATION_ID¶: The metadata attribute(s) used to identify which articles are translations of one another. May be a string or a collection of strings. Set to None or False to disable the identification of translations. The default is "slug".

PAGE_TRANSLATION_ID¶: The metadata attribute(s) used to identify which pages are translations of one another. May be a string or a collection of strings. Set to None or False to disable the identification of translations. The default is "slug".

TRANSLATION_FEED_ATOM¶: The location to save the Atom feed for translations. [3] The default is "feeds/all-{lang}.atom.xml".

TRANSLATION_FEED_ATOM_URL¶: 指定各翻译Atom feed的含有 {lang} 的相对URL。 [3] 若未设置此项，TRANSLATION_FEED_ATOM 会同时用于存储位置和URL。本项配置默认为 None 。

TRANSLATION_FEED_RSS¶: 指定各翻译RSS订阅源的存储位置。本项配置默认为 None ，即无RSS feed。

TRANSLATION_FEED_RSS_URL¶: 文章或页面不同翻译在RSS订阅源中的相对路径，其中含有 {lang}。 [3] 若未设置此项，TRANSLATION_FEED_RSS 会同时用于存储位置和URL。本项配置默认为 None 。

内容的排列顺序¶

NEWEST_FIRST_ARCHIVES¶: 若设为True，日期较新的会排在前面；若设为False，则日期较旧的会排在前面。本项配置默认为 True 。

REVERSE_CATEGORY_ORDER¶: 若设为True，分类会按字典序逆序排列；若设为False，则按字典序顺序排列。本项配置默认为 False 。

ARTICLE_ORDER_BY¶: Defines how the articles (articles_page.object_list in the template) are sorted. Valid options are: metadata as a string (use reversed- prefix to 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. Using a value of "date" will sort articles in chronological order, while the default value, "reversed-date", will sort articles by date in reverse order (i.e., newest article comes first). The default is "reversed-date".

PAGE_ORDER_BY¶: 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. The default is "basename".

主题¶

创建Pelican主题在单独的一节中讲解（参见主题）。此处讲解和主题有关的配置项。

THEME¶: 用于产生输出的主题。可以是到达要使用主题的文件夹的相对或绝对路径，或是主题的名称（默认主题或通过 pelican-themes 安装的主题）。默认主题为 "notmyidea" 。

THEME_STATIC_DIR¶: Destination directory in the output path where Pelican will place the files collected from THEME_STATIC_PATHS. Default is theme. The default is "theme".

THEME_STATIC_PATHS¶: 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. The default is ["static"].

THEME_TEMPLATES_OVERRIDES¶

在搜索主题的 templates/ 目录前，Jinja2会先搜索此设置项中的路径。可以使用此设置项覆盖主题中的某些模板文件，以尽量避免修改现有主题。Jinja2会先搜索 THEME_TEMPLATES_OVERRIDES 配置的文件，再搜索主题中的 templates/ 目录。本项配置默认为 [] 。

利用 {% extends %} 指令中的 !theme 前缀也可以用于从主题扩展模板，如下例所示：

{% extends '!theme/article.html' %}

CSS_FILE¶: Specify the CSS file you want to load. The default is "main.css".

默认情况下，有两个主题可供选择。可以使用 THEME 选项指定，或是在 pelican 命令中使用 -t 选项的参数传入。

notmyidea（默认值）
simple（即“plain text”）

还有很多主题可以在 https://github.com/getpelican/pelican-themes 上下载。Pelican使用一个称为 pelican-themes 的小脚本来管理主题。

你还可以创建自己的主题，可以从头开始，也可以在已有主题的基础上修改。请参看主题文档。

下面是几个指定某个主题的例子：

# 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"

Simple Theme¶

The built-in simple theme can be customized using the following settings:

STYLESHEET_URL¶: 要使用的样式表的URL。本项配置默认为 None 。

下面的一下选项可以很好地作用于内置的 notmyidea 主题。当然在其他主题中你也可以尽情尝试这些选项。

SITESUBTITLE¶: 页面顶部要显示的副标题。本项配置默认为 None 。

DISQUS_SITENAME¶: 可以在Pelican中使用Disqus的评论系统，此设置项用于设置Disqus的站点标识符。本项配置默认为 None 。

GITHUB_URL¶: 指定你的GitHub URL（如果有的话），此信息将被用于创建GitHub标记。本项配置默认为 None 。

ANALYTICS¶

在 publishconf.py 中设置此项，用于指定想要使用的统计分析脚本。如下例：

ANALYTICS = """
    <script src="/theme/js/primary-analytics.js"></script>
    <script>
        [ … in-line Javascript code for secondary analytics … ]
    </script>
"""

默认为 None

MENUITEMS¶: 指定 (标题, URL) 元组的列表，用于指定额外的菜单项，会添加在菜单栏的开头。本项配置默认为 None 。

LINKS¶: 指定 (标题, URL) 元组的列表，用于指定要展示在顶部的链接。本项配置默认为 None 。

SOCIAL¶: 指定 (标题, URL) 元组的列表，用于指定要展示在“social”部分的内容。本项配置默认为 None 。

TWITTER_USERNAME¶: 允许在文章中添加按钮，以便其他人在tweet上引用。如果希望显示此按钮，在此项中设置你的Twitter用户名。本项配置默认为 None 。

LINKS_WIDGET_NAME¶: 指定用于覆盖“links”部分的名称，若不指定，默认设为 “links”。本项配置默认为 None 。

SOCIAL_WIDGET_NAME¶: 指定用于覆盖“social”部分的名称。若不指定，默认设为 “social”。本项配置默认为 None 。

Notmyidea Theme¶

另外，你可以使用 notmyidea 主题的“宽屏”版本，在配置文件中添加下面这行配置即可：

CSS_FILE = "wide.css"

日志¶

在站点生成过程中有时可能会出现一堆警告信息。在这一大堆日志输出中寻找 有意义 的错误消息是非常棘手的。为了过滤掉多余的日志消息，可以在Pelican中指定 LOG_FILTER 设置。

LOG_FILTER 是元组 (level, msg) ，level指定日志记录等级（最高为 warning ），msg指定要忽略的消息。将想要隐藏的日志消息添加到此列表中就可以将他们过滤掉。

例如：

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

用模板字符串指定要过滤的消息也是可以的。具体的消息种类请查看源码。

例如：

import logging
LOG_FILTER = [(logging.WARN, "Empty alt attribute for image %s in %s")]

警告

通过模板过滤忽略消息是一个危险的功能。使用同一模板可能会无意中过滤掉多种消息类型（包括来自新版本Pelican的消息），请谨慎行事。

备注

当使用了 --debug 参数，此项设置就不会起作用。

Reading Only Modified Content¶

为了加速网站构建过程，Pelican能够只读取修改过内容的文章和页面。

当Pelican准备读取内容源文件时，会执行下面的规则：

若 LOAD_CONTENT_CACHE 为 True ，则从缓存文件中加载上一次构建时文件的哈希值或修改时间。这些缓存的文件存储在 CACHE_PATH 所指定的目录中。若文件是新的，在缓存文件中没有记录，则照常读取。
文件会以 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.
- 如果设置为其他任何值或在缓存文件中无法找到有关该文件的必要信息，则将照常读取内容。
如果Pelican认为文件没有更改过，会直接从上一次构建的对应文件中加载内容，源文件就不会被读取。
若Pelican认为文件更改过了，则会读取源文件；若 CACHE_CONTENT 设为了 True ，Pelican还会将修改后的信息以及内容数据存入缓存。

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

检查文件修改时间比计算文件哈希更快，但事实上却不太可靠，因为 mtime 信息有丢失的可能。例如，使用 cp 或 rsync 命令时没有开启 mtime 保留模式。（rsync可以通过指定 --archive 标志启用 mtime 保留模式）

缓存文件使用的是Python pickles，因此不同版本的Python由于pickle文件格式变化可能无法读取缓存。如果遇到此类错误，会自动以新格式重新构建缓存。另外，当 GZIP_CACHE 设置发生变化后，缓存也会自动重建。

当需要重新生成整个缓存时，可以使用 --ignore-cache 命令行选项，例如当需要修改会影响缓存内容的设置项时，或是调试时，都可以使用 --ignore-cache 。若 AUTORELOAD_IGNORE_CACHE 设为了 True ，修改设置文件时会自动忽略缓存。

需要注意的是，即使使用了缓存的内容，最终的输出文件也始终会进行重新写入，因此生成的 *.html 文件的修改时间始终会变化。所以，基于 rsync 进行上传时，可以考虑使用 --checksum 选项。

配置示例¶

AUTHOR = "Alexis Métaireau"
SITENAME = "Alexis' log"
SITESUBTITLE = "A personal blog."
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/{slug}.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 = [
    "images",
    "extra/robots.txt",
]

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

# there is no other HTML content
READERS = {"html": None}

# 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"