设置¶
Pelican是可配置的,这要归功于您可以传递到命令行的设置文件:
pelican content -s path/to/your/pelicanconf.py
如果你用 pelican-quickstart
命令,您的主设置文件将被命名为 pelicanconf.py
默认情况下。
您也可以通过 -e
/ --extra-settings
选项标志,它将覆盖默认设置以及设置文件中定义的任何设置:
pelican content -e DELETE_OUTPUT_DIRECTORY=true
注解
当尝试使用不同的设置(尤其是元数据设置)时,缓存可能会干扰,并且更改可能不可见。在这种情况下,使用禁用缓存 LOAD_CONTENT_CACHE = False
或者使用 --ignore-cache
命令行开关。
设置以Python模块(文件)的形式配置。有一个 example settings file 可供参考。
要查看环境中当前设置的列表,包括默认值和任何自定义值,请运行以下命令(附加一个或多个特定的设置名称作为参数,以便仅查看这些设置的值):
pelican --print-settings
所有设置标识符必须设置为所有大写字母,否则将不处理它们。设置数字(5、20等)、布尔值(True、False、None等)、字典或元组的值应该 not 用引号括起来。所有其他值(即字符串) must 用引号括起来。
除非另有规定,否则引用路径的设置可以是绝对的,也可以是相对于配置文件的。您在配置文件中定义的设置将传递给模板,模板允许您使用设置添加站点范围的内容。
以下是Pelican的设置列表:
基本设置¶
-
USE_FOLDER_AS_CATEGORY = True
如果未在post元数据中指定类别,请将此设置设置为
True
,并将文章组织到子文件夹中,则该子文件夹将成为您文章的类别。如果设置为False
,DEFAULT_CATEGORY
将用作备用。
-
DEFAULT_CATEGORY = 'misc'
要依赖的默认类别。
-
DISPLAY_PAGES_ON_MENU = True
是否在模板的菜单上显示页面。模板可能支持也可能不支持此设置。
-
DISPLAY_CATEGORIES_ON_MENU = True
是否在模板的菜单上显示类别。模板可能不支持此设置。
-
DOCUTILS_SETTINGS = {}
docutils发布程序的额外配置设置(仅适用于RestructedText)。看到了吗 Docutils Configuration 设置以获取更多详细信息。
-
DELETE_OUTPUT_DIRECTORY = False
删除输出目录,然后 all 在生成新文件之前。这有助于防止旧的、不必要的文件保留在输出中。然而, 这是一个破坏性的设置,应该非常小心地处理。
-
OUTPUT_RETENTION = []
应该保留而不是从输出目录中删除的文件名的列表。一个用例是保存版本控制数据。
例子:
OUTPUT_RETENTION = [".hg", ".git", ".bzr"]
-
JINJA_ENVIRONMENT = {'trim_blocks': True, 'lstrip_blocks': True}
要使用的自定义Jinja2环境变量的字典。这还包括一个您可能想要包含的扩展名列表。看到了吗 Jinja Environment documentation .
-
JINJA_FILTERS = {}
你想使用的自定义Jinja2过滤器字典。字典应该将filtername映射到filter函数。
- 例子:
导入系统系统路径追加('到/你的/路径')
从自定义过滤器导入urlencode_filter JINJA_FILTERS={'urlencode':urlencode_filter}
-
JINJA_GLOBALS = {}
要映射到Jinja2全局环境名称空间的自定义对象字典。字典应该将全局名称映射到全局变量/函数。参见: Jinja global namespace documentation .
-
JINJA_TESTS = {}
你想使用的自定义Jinja2测试词典。字典应该将测试名称映射到测试函数。参见: Jinja custom tests documentation .
-
LOG_FILTER = []
包含日志记录级别的元组列表(最多
warning
)以及要忽略的信息。例子:
LOG_FILTER = [(logging.WARN, 'TAG_SAVE_AS is set to False')]
-
READERS = {}
供Pelican处理或忽略的文件扩展名/读取器类词典。
例如,要避免处理.html文件,请设置:
READERS = {'html': None}
为添加自定义读取器
foo
扩展,设置:READERS = {'foo': FooReader}
-
IGNORE_FILES = ['.#*']
全局模式列表。处理器将忽略与这些模式匹配的文件和目录。例如,默认值
['.#*']
emacs将忽略文件['__pycache__']
会忽略Python3的字节码缓存。
-
MARKDOWN = {...}
降价处理器的额外配置设置。请参阅Python Markdown文档 Options section 以获取支持选项的完整列表。这个
extensions
选项将自动从extension_configs
选择权。默认为:
MARKDOWN = { 'extension_configs': { 'markdown.extensions.codehilite': {'css_class': 'highlight'}, 'markdown.extensions.extra': {}, 'markdown.extensions.meta': {}, }, 'output_format': 'html5', }
注解
设置文件中定义的词典将替换此默认词典。
-
OUTPUT_PATH = 'output/'
生成文件的输出位置。这应该与web服务器的虚拟主机根目录相对应。
-
PATH
¶ Pelican要处理的内容目录的路径。如果未定义,则未通过参数指定内容路径
pelican
命令,Pelican将使用当前工作目录。
-
PAGE_PATHS = ['pages']
要查找页面的目录和文件的列表,相对于
PATH
.
-
PAGE_EXCLUDES = []
在查找除
ARTICLE_PATHS
.
-
ARTICLE_PATHS = ['']
要查看的文章的目录和文件的列表,相对于
PATH
.
-
ARTICLE_EXCLUDES = []
在查找除
PAGE_PATHS
.
-
OUTPUT_SOURCES = False
如果要将文章和页面的原始格式(例如Markdown或restructedText)复制到指定的
OUTPUT_PATH
.
-
OUTPUT_SOURCES_EXTENSION = '.text'
控制SourcesGenerator将使用的扩展。默认为
.text
. 如果不是有效字符串,将使用默认值。
-
PLUGINS = None
要加载的插件列表。看到了吗 插件 .
-
PLUGIN_PATHS = []
查找插件的目录列表。看到了吗 插件 .
-
SITENAME = 'A Pelican Blog'
您的站点名称
-
SITEURL
¶ 网站的基本URL。默认情况下没有定义,因此最好指定您的SITEURL;如果不这样做,则不会使用格式正确的URL生成提要。如果您的站点可通过HTTPS访问,则此设置应以
https://
-否则使用http://
. 然后附加你的域,结尾不带斜杠。例子:SITEURL = 'https://example.com'
-
STATIC_PATHS = ['images']
目录列表(相对于
PATH
)在其中查找静态文件。这样的文件将被复制到输出目录而不做任何修改。文章、页面和其他内容源文件通常会被跳过,因此目录在此处和中同时出现是安全的PAGE_PATHS
或ARTICLE_PATHS
. Pelican的默认设置包括这里的“images”目录。
-
STATIC_EXCLUDES = []
查找静态文件时要排除的目录列表。
-
STATIC_EXCLUDE_SOURCES = True
如果设置为False,则在复制中找到的文件时不会跳过内容源文件
STATIC_PATHS
. 此设置用于向后兼容Pelican 3.5版之前的版本。它没有效果,除非STATIC_PATHS
包含一个目录ARTICLE_PATHS
或PAGE_PATHS
. 如果要发布站点的源文件,请考虑使用OUTPUT_SOURCES
改为设置。
-
STATIC_CREATE_LINKS = False
创建链接而不是复制文件。如果内容和输出目录在同一设备上,则创建硬链接。如果输出目录在不同的文件系统上,则返回到符号链接。如果创建了符号链接,不要忘记添加
-L
或--copy-links
上传站点时rsync选项。
-
STATIC_CHECK_IF_MODIFIED = False
如果设置为
True
和STATIC_CREATE_LINKS
是False
,比较内容和输出文件的mtimes,只复制比现有输出文件更新的内容文件。
-
TYPOGRIFY = False
如果设置为True,将通过 Typogrify 库,可通过以下方式安装:
python -m pip install typogrify
-
TYPOGRIFY_IGNORE_TAGS = []
typegrify要忽略的标记列表。默认情况下,typegrify将忽略
pre
和code
标签。这需要安装TypeGrify 2.0.4或更高版本
-
TYPOGRIFY_DASHES = 'default'
此设置控制typegrify如何设置Smartypants过滤器以解释多个短划线/连字符/减号字符。一个ASCII短划线字符 (
-
)始终呈现为连字符。这个default
设置不处理短划线,并将双连字符转换为em短划线。这个oldschool
设置在看到两个破折号时同时呈现en破折号和em破折号 (--
)还有三个 (---
)分别是连字符。这个oldschool_inverted
设置将两个连字符转换为em短划线,将三个连字符转换为en短划线。
-
SUMMARY_MAX_LENGTH = 50
当创建一篇文章的简短摘要时,这将是所创建文本的默认长度(以单词度量)。这仅适用于您的内容没有以其他方式指定摘要的情况。设置为
None
将导致摘要成为原始内容的副本。
-
SUMMARY_END_SUFFIX = '…'
当创建一篇文章的简短摘要并且结果被截断以匹配所需的单词长度时,这将被用作截断后缀。
-
WITH_FUTURE_DATES = True
如果禁用,则具有将来日期的内容将获得默认状态
draft
. 见 只读修改内容 注意事项。
-
INTRASITE_LINK_REGEX = '[{|](?P<what>.*?)[|}]'
用于分析内部链接的正则表达式。链接到内部文件、标记等时的默认语法是将标识符括起来,例如
filename
在{{}}
或||
. 标识符介于{{
和}}
进入what
正在捕获组。有关详细信息,请参阅 链接到内部内容 .
-
PYGMENTS_RST_OPTIONS = []
ReconstructedText代码块的默认Pygments设置列表。看到了吗 语法突出显示 以获取支持选项的列表。
-
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 = []
如果此列表不为空, only 输出文件及其路径在此列表中被写入。路径应该是绝对的或相对于当前的Pelican工作目录。有关可能的用例,请参见 仅写入选定内容 .
-
FORMATTED_FIELDS = ['summary']
包含要解析并转换为HTML的reST/Markdown内容的元数据字段列表。
-
PORT = 8000
当pelican使用--listen运行时,通过HTTP从输出文件夹提供内容的TCP端口
-
BIND = ''
要将HTTP服务器绑定到的IP。
URL设置¶
首先要了解的是,目前有两种支持的URL形成方法: 相对的 和 绝对的 . 相对URL在本地测试时很有用,绝对URL是可靠的,在发布时最有用。支持两者的一种方法是使用一个Pelican配置文件进行本地开发,另一个用于发布。要查看此类设置的示例,请使用 pelican-quickstart
脚本如中所述 Installation 部分,它将分别为本地开发和发布生成两个单独的配置文件。
您可以自定义保存文件的URL和位置。这个 *_URL
和 *_SAVE_AS
使用Python的字符串格式变量。这些变量允许您将文章放在诸如 {{slug}}/index.html
并将其链接为 {{slug}}
对于干净的URL(见下面的示例)。这些设置使您能够灵活地将文章和页面放在任何您想要的位置。
注解
如果A *_SAVE_AS
设置包含的父目录与对应的 *_URL
设置时,这可能会导致Pelican在某些情况下生成意外的URL,例如在使用 {{attach}}
语法。
如果您不希望这种灵活性,而是希望生成的输出路径镜像源内容的文件系统路径层次结构,请尝试以下设置:
PATH_METADATA = '(?P<path_no_ext>.*)\..*'
ARTICLE_URL = ARTICLE_SAVE_AS = PAGE_URL = PAGE_SAVE_AS = '{path_no_ext}.html'
否则,可以在URL相关设置中使用各种文件元数据属性:
slug
日期
朗
作者
类别
示例用法:
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
,并在 /posts/2011/Aug/07/sample-post/
和 /pages/about/
,分别。
注解
If you specify a datetime
directive, it will be substituted using the
input files' date metadata attribute. If the date is not specified for a
particular file, Pelican will rely on the file's mtime
timestamp. Check
the Python datetime documentation for more information.
-
RELATIVE_URLS = False
定义Pelican是否应使用文档相对URL。只需将此设置为
True
当开发/测试时,并且只有当您完全理解它对链接/提要的影响时。
-
ARTICLE_URL = '{slug}.html'
引用文章的URL。
-
ARTICLE_SAVE_AS = '{slug}.html'
保存文章的地方。
-
ARTICLE_LANG_URL = '{slug}-{lang}.html'
指向不使用默认语言的文章的URL。
-
ARTICLE_LANG_SAVE_AS = '{slug}-{lang}.html'
保存不使用默认语言的文章的位置。
-
DRAFT_URL = 'drafts/{slug}.html'
引用文章草稿的URL。
-
DRAFT_SAVE_AS = 'drafts/{slug}.html'
保存文章草稿的地方。
-
DRAFT_LANG_URL = 'drafts/{slug}-{lang}.html'
指向不使用默认语言的文章草稿的URL。
-
DRAFT_LANG_SAVE_AS = 'drafts/{slug}-{lang}.html'
保存不使用默认语言的文章草稿的位置。
-
PAGE_URL = 'pages/{slug}.html'
我们将用于链接到页面的URL。
-
PAGE_SAVE_AS = 'pages/{slug}.html'
保存页面的位置。此值必须与PAGE_URL相同,否则需要在服务器配置中使用重写。
-
PAGE_LANG_URL = 'pages/{slug}-{lang}.html'
我们将用于链接到不使用默认语言的页面的URL。
-
PAGE_LANG_SAVE_AS = 'pages/{slug}-{lang}.html'
我们将保存不使用默认语言的页面的位置。
-
DRAFT_PAGE_URL = 'drafts/pages/{slug}.html'
用于链接到页面草稿的URL。
-
DRAFT_PAGE_SAVE_AS = 'drafts/pages/{slug}.html'
保存页面草稿的实际位置。
-
DRAFT_PAGE_LANG_URL = 'drafts/pages/{slug}-{lang}.html'
用于链接到不使用默认语言的页面草稿的URL。
-
DRAFT_PAGE_LANG_SAVE_AS = 'drafts/pages/{slug}-{lang}.html'
不使用默认语言的页面草稿保存在的实际位置。
-
AUTHOR_URL = 'author/{slug}.html'
用于作者的URL。
-
AUTHOR_SAVE_AS = 'author/{slug}.html'
保存作者的位置。
-
CATEGORY_URL = 'category/{slug}.html'
用于类别的URL。
-
CATEGORY_SAVE_AS = 'category/{slug}.html'
保存类别的位置。
-
TAG_URL = 'tag/{slug}.html'
用于标记的URL。
-
TAG_SAVE_AS = 'tag/{slug}.html'
保存标记页的位置。
注解
如果您不希望创建一个或多个默认页面(例如,您是站点上唯一的作者,因此不需要作者页面),请设置相应的 *_SAVE_AS
设置为 ''
以防止生成相关页面。
Pelican可以选择创建每年,每月,每天你的职位档案。默认情况下,这些辅助存档处于禁用状态,但如果您为它们各自提供格式字符串,则会自动启用它们 _SAVE_AS
设置。Period存档直观地符合web url的层次模型,并且可以使读者更容易地浏览您随时间撰写的文章。
示例用法:
YEAR_ARCHIVE_SAVE_AS = 'posts/{date:%Y}/index.html'
MONTH_ARCHIVE_SAVE_AS = 'posts/{date:%Y}/{date:%b}/index.html'
佩利肯将为你的所有职位创建一个档案 posts/2011/index.html
还有一个你这个月所有帖子的档案 posts/2011/Aug/index.html
.
注解
当最终路径段为 index.html
. 这样,读者就可以删除你的URL的一部分,并自动到达一个适当的文章存档,而不必指定页面名称。
-
YEAR_ARCHIVE_URL = ''
你的文章每年存档使用的URL。只有当你有
{{url}}
占位符PAGINATION_PATTERNS
.
-
YEAR_ARCHIVE_SAVE_AS = ''
每年保存你的文章档案的位置。
-
MONTH_ARCHIVE_URL = ''
用于每月存档文章的URL。只有当你有
{{url}}
占位符PAGINATION_PATTERNS
.
-
MONTH_ARCHIVE_SAVE_AS = ''
每月保存文章档案的位置。
-
DAY_ARCHIVE_URL = ''
用于每天存档文章的URL。只有当你有
{{url}}
占位符PAGINATION_PATTERNS
.
-
DAY_ARCHIVE_SAVE_AS = ''
每天保存你的文章档案的位置。
DIRECT_TEMPLATES
工作有点不同于上面提到的。只有 _SAVE_AS
设置可用,但可用于任何直接模板。
-
ARCHIVES_SAVE_AS = 'archives.html'
保存文章存档页的位置。
-
AUTHORS_SAVE_AS = 'authors.html'
保存作者列表的位置。
-
CATEGORIES_SAVE_AS = 'categories.html'
保存类别列表的位置。
-
TAGS_SAVE_AS = 'tags.html'
保存标记列表的位置。
-
INDEX_SAVE_AS = 'index.html'
保存所有项目列表的位置。
直接模板页面的URL依赖于主题。有些主题使用相应的 *_URL
设置为字符串,而其他人硬编码它们: 'archives.html'
, 'authors.html'
, 'categories.html'
, 'tags.html'
.
-
SLUGIFY_SOURCE = 'title'
指定要自动生成段塞的位置。可以设置为
title
使用“Title:”元数据标记或basename
在创建slug时使用文章的文件名。
-
SLUGIFY_USE_UNICODE = False
允许在段塞中使用Unicode字符。设置
True
在自动生成的段中保留Unicode字符。否则,Unicode字符将替换为ASCII等效字符。
-
SLUGIFY_PRESERVE_CASE = False
保留段塞中的大写字符。设置
True
防止大写字符SLUGIFY_SOURCE
原来如此。
-
SLUG_REGEX_SUBSTITUTIONS = [
-
(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 '-'
-
]
生成文章和页面的段塞时要进行的正则表达式替换。指定为对的列表
(from, to)
顺序应用,忽略大小写。默认替换的效果是删除非字母数字字符并将内部空白转换为破折号。除了这些替换之外,slug总是被转换成小写的ascii字符,并且去掉前导和尾随的空白。有助于与现有URL向后兼容。
-
AUTHOR_REGEX_SUBSTITUTIONS = SLUG_REGEX_SUBSTITUTIONS
正则表达式替换为作者slug。默认为
SLUG_REGEX_SUBSTITUTIONS
.
-
CATEGORY_REGEX_SUBSTITUTIONS = SLUG_REGEX_SUBSTITUTIONS
类段塞的正则表达式替换。默认为
SLUG_REGEX_SUBSTITUTIONS
.
-
TAG_REGEX_SUBSTITUTIONS = SLUG_REGEX_SUBSTITUTIONS
标记段塞的正则表达式替换。默认为
SLUG_REGEX_SUBSTITUTIONS
.
时间和日期¶
-
TIMEZONE
¶ 日期信息中用于生成Atom和RSS提要的时区。
如果没有定义时区,则假定为UTC。这意味着,如果您的语言环境不是UTC,则生成的Atom和RSS提要将包含不正确的日期信息。
Pelican在未定义此设置的情况下发出警告,因为它在以前的版本中不是必需的。
看一看 the wikipedia page 获取有效时区值的列表。
-
DEFAULT_DATE = None
要使用的默认日期。如果
'fs'
,如果无法从元数据中获取日期信息,则Pelican将使用文件系统时间戳信息(mtime)。如果给定任何其他字符串,则将使用与项目元数据相同的方法对其进行解析。如果设置为tuple对象,则将通过将tuple传递给datetime.datetime
建造师。
-
DEFAULT_DATE_FORMAT = '%a %d %B %Y'
要使用的默认日期格式。
-
DATE_FORMATS = {}
如果您管理多种语言,可以在此处设置日期格式。
如果没有
DATE_FORMATS
都准备好了,Pelican就要倒下了DEFAULT_DATE_FORMAT
. 如果需要维护具有不同日期格式的多种语言,可以设置DATE_FORMATS
使用语言名称的词典 (lang
你的文章内容中的元数据)作为密钥。除中列出的标准C89 strftime格式代码外 Python datetime documentation ,您可以使用
-
字符介于%
以及格式字符以删除任何前导零。例如,%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
¶ 更改区域设置 1. 可以在这里提供区域设置列表,也可以提供表示一个区域设置的单个字符串。当提供列表时,将尝试所有区域设置,直到其中一个可用为止。
您可以设置区域设置以进一步控制日期格式:
LOCALE = ('usa', 'jpn', # On Windows 'en_US', 'ja_JP' # On Unix/Linux )
有关可用区域设置的列表,请参阅 locales on Windows 或者在Unix/Linux上,使用
locale -a
命令;请参阅手册页 locale(1) 更多信息。
- 1
默认为系统区域设置。
模板页¶
-
TEMPLATE_PAGES = None
一个映射,其中包含将与博客条目一起呈现的模板页面。
如果您想在博客条目之外生成自定义页面,您可以指向任何Jinja2模板文件,其中包含指向该文件的路径和生成文件的目标路径。
例如,如果你有一个有三个静态页面的博客,一个图书列表,你的简历,一个联系人页面,你可以有:
TEMPLATE_PAGES = {'src/books.html': 'dest/books.html', 'src/resume.html': 'dest/resume.html', 'src/contact.html': 'dest/contact.html'}
-
TEMPLATE_EXTENSIONS = ['.html']
从模板名称中查找模板文件时要使用的扩展名。
-
DIRECT_TEMPLATES = ['index', 'authors', 'categories', 'tags', 'archives']
直接用于呈现内容的模板列表。通常直接模板用于为内容集合生成索引页(例如,类别和标记索引页)。如果不需要author、category和tag集合,则设置
DIRECT_TEMPLATES = ['index', 'archives']
DIRECT_TEMPLATES
搜索中维护的路径THEME_TEMPLATES_OVERRIDES
.
元数据¶
-
AUTHOR
¶ 默认作者(通常是您的姓名)。
-
DEFAULT_METADATA = {}
要用于所有项目和页面的默认元数据。
-
FILENAME_METADATA = r'(?P<date>\d{4}-\d{2}-\d{2}).*'
将用于从文件名中提取任何元数据的regexp。所有匹配的命名组都将在元数据对象中设置。默认值将只从文件名中提取日期。
例如,要同时提取日期和段塞:
FILENAME_METADATA = r'(?P<date>\d{4}-\d{2}-\d{2})_(?P<slug>.*)'
也见
SLUGIFY_SOURCE
.
-
PATH_METADATA = ''
喜欢
FILENAME_METADATA
,但从页面相对于内容源目录的完整路径进行分析。
-
EXTRA_PATH_METADATA = {}
由相对路径键控的额外元数据字典。相对路径需要正确的操作系统特定的目录分隔符(例如,在UNIX中为./在Windows中为\),与其他一些Pelican文件设置不同。指向某个目录的路径将应用于该目录下的所有文件。最具体的路径会赢得冲突。
并非所有元数据都需要 embedded in source file itself . 例如,博客文章通常以 YYYY-MM-DD-SLUG.rst
或者嵌套到 YYYY/MM/DD-SLUG
目录。要从文件名或路径中提取元数据,请设置 FILENAME_METADATA
或 PATH_METADATA
使用Python的 group name notation (?P<name>…)
. 如果要附加附加元数据,但不想在路径中对其进行编码,可以设置 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',
},
}
这是移动特定文件的安装位置的方便方法:
# 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'},
}
源设置¶
默认情况下,Pelican使用Atom提要。不过,如果您愿意,也可以使用RSS提要。
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 "/"
域预先添加了源URL。因为feed url应该始终是绝对的,所以强烈建议定义它(例如,在https://feeds.example.com"). 如果您已经明确定义了SITEURL(见上文),并希望将同一域用于提要,则可以设置:
FEED_DOMAIN = SITEURL
.
-
FEED_ATOM = None, i.e. no Atom feed
保存Atom源的位置。
-
FEED_ATOM_URL = None
Atom源的相对URL。如果未设置,
FEED_ATOM
同时用于保存位置和URL。
-
FEED_RSS = None, i.e. no RSS
保存RSS源的位置。
-
FEED_RSS_URL = None
RSS源的相对URL。如果未设置,
FEED_RSS
同时用于保存位置和URL。
-
FEED_ALL_ATOM = 'feeds/all.atom.xml'
保存all posts Atom提要的位置:此提要将包含所有帖子,而不管其语言如何。
-
FEED_ALL_ATOM_URL = None
所有帖子Atom提要的相对URL。如果未设置,
FEED_ALL_ATOM
同时用于保存位置和URL。
-
FEED_ALL_RSS = None, i.e. no all-posts RSS
保存allpostsrss提要的位置:这个提要将包含所有文章,而不管它们的语言是什么。
-
FEED_ALL_RSS_URL = None
所有帖子RSS源的相对URL。如果未设置,
FEED_ALL_RSS
同时用于保存位置和URL。
-
CATEGORY_FEED_ATOM = 'feeds/{slug}.atom.xml'
保存类别Atom提要的位置。 2
-
CATEGORY_FEED_ATOM_URL = None
类别Atom提要的相对URL,包括
{{slug}}
占位符。 2 如果未设置,CATEGORY_FEED_ATOM
同时用于保存位置和URL。
-
CATEGORY_FEED_RSS = None, i.e. no RSS
保存类别RSS提要的位置,包括
{{slug}}
占位符。 2
-
CATEGORY_FEED_RSS_URL = None
类别RSS提要的相对URL,包括
{{slug}}
占位符。 2 如果未设置,CATEGORY_FEED_RSS
同时用于保存位置和URL。
-
AUTHOR_FEED_ATOM = 'feeds/{slug}.atom.xml'
保存作者Atom源的位置。 2
-
AUTHOR_FEED_ATOM_URL = None
作者Atom提要的相对URL,包括
{{slug}}
占位符。 2 如果未设置,AUTHOR_FEED_ATOM
同时用于保存位置和URL。
-
AUTHOR_FEED_RSS = 'feeds/{slug}.rss.xml'
保存作者RSS源的位置。 2
-
AUTHOR_FEED_RSS_URL = None
作者RSS源的相对URL,包括
{{slug}}
占位符。 2 如果未设置,AUTHOR_FEED_RSS
同时用于保存位置和URL。
-
TAG_FEED_ATOM = None, i.e. no tag feed
保存标记Atom提要的位置,包括
{{slug}}
占位符。 2
-
TAG_FEED_ATOM_URL = None
标记Atom提要的相对URL,包括
{{slug}}
占位符。 2
-
TAG_FEED_RSS = None, i.e. no RSS tag feed
输出标记RSS提要的相对URL,包括
{{slug}}
占位符。如果未设置,TAG_FEED_RSS
同时用于保存位置和URL。
-
FEED_MAX_ITEMS
¶ 源中允许的最大项数。进给项目数量默认不受限制。
-
RSS_FEED_SUMMARY_ONLY = True
仅在
description
RSS源的标签。如果设置为False
,则会包含全部内容。此设置不影响Atom订阅源,只影响RSS订阅源。
如果不想生成这些提要中的一些或任何一个,请将上述变量设置为 None
.
分页¶
Pelican的默认行为是在索引页上列出所有文章标题以及简短描述。虽然这对中小型站点很有效,但是有大量文章的站点可能会从分页这个列表中获益。
您可以使用以下设置来配置分页。
-
DEFAULT_ORPHANS = 0
最后一页允许的最小文章数。如果您不希望最后一页只包含少数文章,请使用此选项。
-
DEFAULT_PAGINATION = False
页面上要包含的最大文章数,不包括孤立项。False禁用分页。
-
PAGINATED_TEMPLATES = {'index': None, 'tag': None, 'category': None, 'author': None}
使用分页的模板,以及页面上要包含的文章数。如果该值为
None
,默认为DEFAULT_PAGINATION
.
-
PAGINATION_PATTERNS = (
-
(1, '{name}{extension}', '{name}{extension}'),
-
(2, '{name}{number}{extension}', '{name}{number}{extension}'),
-
)
用于确定高级分页输出的一组模式。
使用分页模式¶
默认情况下 .../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}}
等于页码。
例如,如果要保持第一页不变,但将后续页放在 .../page/2/
等等,你可以 PAGINATION_PATTERNS
如下:
PAGINATION_PATTERNS = (
(1, '{url}', '{save_as}'),
(2, '{base_name}/page/{number}/', '{base_name}/page/{number}/index.html'),
)
翻译¶
Pelican提供了一种翻译文章的方法。见 Content 有关详细信息,请参阅。
-
DEFAULT_LANG = 'en'
要使用的默认语言。
-
ARTICLE_TRANSLATION_ID = 'slug'
元数据属性,用于标识哪些项目是彼此的翻译。可以是字符串或字符串的集合。设置为
None
或False
禁用翻译标识。
-
PAGE_TRANSLATION_ID = 'slug'
元数据属性,用于标识哪些页面是彼此的翻译。可以是字符串或字符串的集合。设置为
None
或False
禁用翻译标识。
-
TRANSLATION_FEED_ATOM = 'feeds/all-{lang}.atom.xml'
保存Atom提要以供翻译的位置。 3
-
TRANSLATION_FEED_ATOM_URL = None
用于翻译的Atom提要的相对URL,包括
{{lang}}
占位符。 3 如果未设置,TRANSLATION_FEED_ATOM
同时用于保存位置和URL。
-
TRANSLATION_FEED_RSS = None, i.e. no RSS
将RSS源放在何处进行翻译。
-
TRANSLATION_FEED_RSS_URL = None
用于翻译的RSS源的相对URL,包括
{{lang}}
占位符。 3 如果未设置,TRANSLATION_FEED_RSS
同时用于保存位置和URL。
内容排序¶
-
NEWEST_FIRST_ARCHIVES = True
先按最新日期订购档案。(错误:先按日期订购旧产品。)
-
REVERSE_CATEGORY_ORDER = False
颠倒分类顺序。(True:按字母顺序反向列出;默认按字母顺序列出。)
-
ARTICLE_ORDER_BY = 'reversed-date'
如何定义文章 (
articles_page.object_list
在模板中)进行排序。有效的选项有:metadata as a string(使用reversed-
前缀与排序顺序相反),特殊选项'basename'
它将使用文件的基名(不带路径)或自定义函数从项目中提取排序键。默认值,'reversed-date'
,将按日期倒序排序文章(即最新文章排在第一位)。
-
PAGE_ORDER_BY = 'basename'
定义页面如何 (
pages
模板中的变量)进行排序。选项与ARTICLE_ORDER_BY
. 默认值,'basename'
将按基名称对页进行排序。
主题¶
创造Pelican的主题是在一个专门的部分(见 创作主题 ). 但是,下面是与主题相关的设置。
-
THEME_STATIC_DIR = 'theme'
输出路径中的目标目录,Pelican将在其中放置从中收集的文件 THEME_STATIC_PATHS . 默认是 theme .
-
THEME_STATIC_PATHS = ['static']
要复制的静态主题路径。默认值为 static ,但如果你的主题有其他静态路径,你可以把它们放在这里。如果在此设置中定义的路径中包含具有相同名称的文件或目录,则它们将逐渐被覆盖。
-
THEME_TEMPLATES_OVERRIDES = []
您希望Jinja2在搜索主题之前搜索模板的路径列表
templates/
目录。允许重写单个主题模板文件,而不必派生现有主题。Jinja2按以下顺序搜索:文件THEME_TEMPLATES_OVERRIDES
首先,主题是templates/
.也可以使用
{{% extends %}}
指令使用!theme
前缀如下例所示:{% extends '!theme/article.html' %}
-
CSS_FILE = 'main.css'
指定要加载的CSS文件。
默认情况下,有两个主题可用。可以使用 THEME
设置或通过 -t
选择权 pelican
命令:
不是我的主意
简单(“纯文本”的同义词):
还有许多其他主题可在https://github.com/getpelican/pelican-themes。Pelican Pelican主题 ,一个管理主题的小脚本。
您可以定义自己的主题,可以从头开始,也可以复制和修改预先存在的主题。给你 a guide on how to create your 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"
内置的 notmyidea
主题可以很好地利用以下设置。在你的主题中也可以随意使用它们。
-
SITESUBTITLE
¶ 标题中出现的副标题。
-
DISQUS_SITENAME
¶ Pelican可以处理不喜欢的评论。在此处指定discus sitename标识符。
-
GITHUB_URL
¶ 你的GitHub URL(如果你有)。然后它将使用这些信息来创建GitHub功能区。
-
GOOGLE_ANALYTICS
¶ 设置为
UA-XXXXX-Y
属性的跟踪ID以激活Google Analytics。
-
GA_COOKIE_DOMAIN
¶ 设置Google Analytics跟踪代码的cookie域字段。默认为
auto
.
-
GOSQUARED_SITENAME
¶ 设置为“XXX-yyyyy-X”以激活GoSquared。
-
MENUITEMS
¶ 显示在主菜单开始处的附加菜单项的元组(标题、URL)列表。
-
LINKS
¶ 链接出现在标头上的元组(标题、URL)列表。
-
SOCIAL
¶ 显示在“社交”部分的元组(标题、URL)列表。
-
TWITTER_USERNAME
¶ 允许在文章中添加一个按钮,以鼓励其他人在tweet上发布文章。如果您想显示此按钮,请添加您的Twitter用户名。
-
LINKS_WIDGET_NAME
¶ 允许重写链接小部件的名称。如果未指定,则默认为“链接”。
-
SOCIAL_WIDGET_NAME
¶ 允许重写“社交”小部件的名称。如果未指定,则默认为“社交”。
此外,您可以使用“宽”版本的 notmyidea
通过将以下内容添加到配置中来创建主题:
CSS_FILE = "wide.css"
登录中¶
有时,站点生成过程中可能会出现一长串警告。找到 有意义的 在大量烦人的日志输出中间出现错误消息可能会非常棘手。为了过滤掉冗余的日志消息,Pelican提供了 LOG_FILTER
设置。
LOG_FILTER
应该是元组的列表 (level, msg)
,每个日志都由日志级别组成(最多 warning
)以及要忽略的信息。只需在列表中填充要隐藏的日志消息,它们就会被过滤掉。
例如:
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
通过。
只读修改内容¶
为了加快构建过程,Pelican可以选择只阅读带有修改内容的文章和页面。
当Pelican要读取某些内容源文件时:
如果出现以下情况,则从缓存文件加载以前生成的文件的哈希或修改时间信息
LOAD_CONTENT_CACHE
是True
. 这些文件存储在CACHE_PATH
目录。如果文件在缓存文件中没有记录,则照常读取。文件检查依据
CHECK_MODIFIED_METHOD
:如果设置为
'mtime'
,检查文件的修改时间。如果设置为由
hashlib
模块,例如。'md5'
,则会检查文件哈希。如果设置为任何其他值或在缓存文件中找不到有关文件的必要信息,则照常读取内容。
如果认为该文件未更改,则会从缓存中加载与该文件对应的先前生成中保存的内容数据,并且不会读取该文件。
如果认为文件已更改,则读取该文件,并且新的修改信息和内容数据将保存到缓存中,如果
CACHE_CONTENT
是True
.
如果 CONTENT_CACHING_LAYER
设置为 'reader'
(默认情况下),将缓存读取器返回的原始内容和元数据。如果此设置改为 'generator'
,则缓存已处理的内容对象。缓存已处理的内容对象可能与插件冲突(因为某些与读取相关的信号可能会被跳过),并且 WITH_FUTURE_DATES
功能(作为 draft
缓存内容对象的状态不会随时间自动更改)。
检查修改时间比比较文件哈希要快,但它不那么可靠,因为 mtime
信息可能会丢失,例如,在使用 cp
或 rsync
没有 mtime
保存模式(用于 rsync
可以通过传递 --archive
标志)。
缓存文件是Python pickle,因此它们可能无法被不同版本的Python读取,因为pickle格式经常更改。如果遇到这样的错误,则会捕捉到该错误,并以新格式自动重建缓存文件。缓存文件也将在 GZIP_CACHE
设置已更改。
这个 --ignore-cache
命令行选项在需要重新生成整个缓存时非常有用,例如在对设置文件进行会影响缓存内容的修改时,或者只是出于调试目的。当Pelican在autoreload模式下运行时,修改设置文件将使其自动忽略缓存,如果 AUTORELOAD_IGNORE_CACHE
是 True
.
请注意,即使使用缓存内容,也始终写入所有输出,因此生成的 *.html
文件总是会更改。因此, rsync
-基于的上载可以从 --checksum
选择权。
仅写入选定内容¶
当只在一篇文章或页面上工作,或对主题进行调整时,通常希望尽快生成并审阅您的工作。在这种情况下,生成和写入整个站点输出通常是不必要的。在中只指定所需的文件作为输出路径 WRITE_SELECTED
列表, only 这些文件将被写入。也可以在命令行上使用 --write-selected
选项,它接受以逗号分隔的输出文件路径列表。默认情况下,此列表为空,因此写入所有输出。看到了吗 站点生成 了解更多详细信息。
示例设置¶
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"