常见问题(FAQ)

以下是一些关于Pelican的常见问题。

沟通问题、问题或建议的最佳方式是什么?

请阅读我们的 feedback guidelines .

我能帮忙吗?

有几种方法可以帮助你。首先,您可以通过IRC(首选)或 issue tracker . 如果提交问题报告,请首先检查现有问题列表(包括打开和关闭),以避免提交重复的问题。

如果你想捐款,请用叉子 the git repository ,创建新的功能分支,进行更改,并发出请求。有人会尽快检查您的更改。请参考 How to Contribute 有关详细信息,请参阅。

您还可以通过创建主题和改进文档来作出贡献。

Pelican设置文件是必需的吗?

配置文件是可选的,只是配置Pelican的一种简单方法。对于基本操作,可以在通过命令行调用Pelican时指定选项。看到了吗 pelican --help 更多信息。

对设置文件的更改无效

当尝试使用不同的设置(尤其是元数据设置)时,缓存可能会干扰,并且更改可能不可见。在这种情况下,请确保通过禁用缓存 LOAD_CONTENT_CACHE = False 或者使用 --ignore-cache 命令行开关。

我在创造我自己的主题。如何使用Pygments来突出显示语法?

Pygments向生成的内容添加一些类。主题使用这些类来设置通过CSS突出显示代码语法的样式。具体来说,您可以通过 .highlight pre 在主题的CSS文件中初始化。例如,要查看如何使用各种样式来呈现Django代码,请使用 Pygments project demo site .

可以使用以下示例命令从Pygments内置样式(在本例中为“monokai”)生成一个起始CSS文件,然后将生成的CSS文件复制到新主题中:

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

别忘了把你的 pygment.css 从你的主CSS文件。

如何创建自己的主题?

请参考 创作主题 .

我想用降价,但我有个错误。

如果您尝试在不首先安装降价库的情况下生成降价内容,可能会看到一条消息 No valid files found in content . 对于Pelican来说,Markdown不是一个硬的依赖项,所以如果您有Markdown格式的内容,那么您需要显式地安装Markdown库。您可以通过键入以下命令来完成此操作 sudo 如果权限要求:

python -m pip install markdown

我可以在模板中使用任意元数据吗?

对。例如,要在降价公告中包含修改日期,可以在文章顶部包含以下内容:

Modified: 2012-08-08

对于reStructuredText,此元数据当然应该以冒号作为前缀:

:Modified: 2012-08-08

然后可以在诸如 article.html 通过:

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

如果您想在文章上下文之外的模板中包含元数据(例如。, base.htmlif 语句应改为:

{% if article and article.modified %}

如何在每页基础上分配自定义模板?

这很简单,只需在想要拥有自己模板的任何页面或文章中添加一行额外的元数据。例如,以下是对reST格式的内容的处理方式:

:template: template_name

对于降价格式的内容:

Template: template_name

然后确保你的主题包含相关的模板文件(例如。 template_name.html

如何覆盖生成的特定页面或文章的URL?

包括 urlsave_as 要覆盖生成的URL的任何页面或文章中的元数据。以下是reST格式的示例页面:

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

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

使用此元数据,页面将被写入 override/url/index.html Pelican会用网址 override/url/ 链接到此页面。

如何使用静态页面作为主页?

可以用上面提到的一个静态页面来替代你的主页。下面的降价示例可以存储在 content/pages/home.md

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

Thank you for visiting. Welcome!

如果仍然需要原始博客索引,则可以通过设置将其保存在其他位置 INDEX_SAVE_AS = 'blog_index.html' 对于 'index' 直接模板。

如果我想禁用feed生成怎么办?

要禁用提要生成,所有提要设置都应设置为 None . 除了三个订阅源设置外,其他所有设置都已默认为 None ,因此,如果要禁用所有源生成,只需指定以下设置:

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

单词 None 不能用引号括起来。请注意 None'' 不是一回事。

我收到了一条关于没有正确设置SITEURL而生成的提要的警告

RSS and Atom feeds require all URL links to be absolute <https://validator.w3.org/feed/docs/rss2.html#comments> _. 为了在Pelican中正确生成链接,您需要设置 SITEURL 到站点的完整路径。

显示此警告时仍会生成提要,但其中的链接可能格式不正确,因此提要可能无法验证。

自从我升级到Pelican 3.x后,我的订阅就断了

从3.0开始,一些FEED设置名称被更改为更明确地引用它们固有的Atom提要(很像FEED_RSS设置名)。以下是重命名设置的精确列表:

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

从3.1开始,新的feed FEED_ALL_ATOM 已经介绍:这个提要将聚合所有的帖子,而不考虑他们的语言。此设置生成 'feeds/all.atom.xml' 默认和 FEED_ATOM 现在默认为 None . 以下源设置也已重命名:

TRANSLATION_FEED -> TRANSLATION_FEED_ATOM

引用旧设置名称的旧主题可能无法正确链接。为了纠正这种情况,请通过更改模板文件中的相关值来更新主题的兼容性。有关完整的提要标题和用法的示例,请查看 simple 主题。

Pelican只适合写博客吗?

不。Pelican可以很容易地配置为创建和维护任何类型的静态站点。这可能需要对你的主题和Pelican配置进行一些定制。例如,如果您正在为您的产品构建一个发布站点,并且站点上不需要标记,则可以从主题中删除相关的HTML代码。也可以通过以下方式禁用标记相关页的生成:

TAGS_SAVE_AS = ''
TAG_SAVE_AS = ''

为什么Pelican总是写入所有HTML文件,即使启用了内容缓存?

为了在编写HTML输出之前可靠地确定HTML输出是否不同,生成环境的很大一部分(包括模板上下文、导入的插件等)都必须保存和比较,至少以哈希的形式(这需要对不易损坏的类型进行特殊处理),因为所有可能的插件组合、分页等都可能以不同的方式改变。这将需要更多的处理时间、内存和存储空间。每次只需简单地编写文件就可以更快、更可靠。

但是,这意味着文件的修改时间每次都会更改,因此 rsync 即使内容没有改变,基于上传的内容也会转移。一个简单的解决方案是 rsync 使用 --checksum 选项,这将使它以比Pelican快得多的方式比较文件校验和。

当只对几个特定的输出文件感兴趣时(例如,在处理某些特定页面或主题模板时) WRITE_SELECTED 选项可能会有所帮助,请参阅 仅写入选定内容 .

如何只处理所有文章的子集?

通常只处理10篇文章以进行调试是很有用的。这可以通过在中显式指定这些项目的文件名来实现 ARTICLE_PATHS . 可以使用类似于 cd content; find -name '*.md' | head -n 10 .

自从我升级Pelican后,我的标签云丢失/损坏

在一个持续的努力蒸汽线Pelican, tag_cloud generation has been moved out of the pelican core and into a separate plugin . 见 插件 有关Pelican插件系统的更多信息。

自从我升级了Pelican我的页面不再呈现

主题可以使用小写形式的页面 pages 和大写 PAGES . 使它与 模板和变量 第节, PAGES 已删除。这可以通过更新主题来快速解决 pages 而不是 PAGES . 只需替换:

{% for pg in PAGES %}

比如:

{% for pg in pages %}

如何阻止Pelican尝试将静态文件解析为内容?

Pelican的文章和页面生成器在静态生成器之前运行。这意味着如果使用类似于默认配置的设置,其中静态源目录在 *_PATHS 设置,所有具有有效内容文件结尾的文件 (.html.rst.md ,…)在被视为静态文件之前将被视为文章或页面。

要避开此问题,请使用适当的 *_EXCLUDES 通过设置或禁用有问题的读卡器 READERS 如果你不需要的话。

为什么是 [任意降价语法] 不支持?

Pelican不直接处理降价处理,而是将该任务委托给 Python-Markdown 项目,其核心有目的地遵循原始的降价语法规则,而不是随后传播的无数降价“风格”。上面说, Python-Markdown 是相当模块化的,并且您正在寻找的语法可能由许多可用的语法之一提供 Markdown Extensions . 或者,有些人已经创建了支持降价变体的Pelican插件,所以如果您想在编写内容时使用特定的变体,那么这可能是您的最佳选择。