Pandoc Reader: Pelican插件

Pandoc Reader 是一个 Pelican 插件，可以将使用 Pandoc 的 Markdown 变体 编写的文档转换为 HTML。

要求

此插件需要

• Python 3.8 或更高版本；以及
• Pandoc 2.11 或更高版本 [Pandoc 安装说明]。

默认情况下，插件会在您的 PATH 中查找 pandoc 可执行文件。如果您愿意，您可以指定 pandoc 可执行文件的其他位置。

安装

此插件可以通过以下方式安装

python -m pip install pelican-pandoc-reader

配置

此插件将 Pandoc 的 Markdown 变体 转换为 HTML。支持从其他 Markdown 变体转换，但需要使用 Pandoc 默认文件。

不支持转换为 HTML 之外的输出格式。

指定文件元数据

插件期望所有 Markdown 文件以以下 YAML 格式的内容标题开头。

---
title: "<post-title>"
author: "<author-name>"
data: "<date>"
---

… 或者 …

---
title: "<post-title>"
author: "<author-name>"
date: "<date>"
...

⚠️ 注意： 上面的 YAML 格式标题是 Pandoc 为指定内容元数据而特定的语法。这与 Pelican 的 front-matter 格式不同。如果您决定停止使用此插件并切换到 Pelican 的默认 Markdown 处理，您可能需要将 front-matter 元数据切换到 Python-Markdown 的 Meta-Data 格式。

如果您有使用 Pelican front matter 格式的文件，Joseph Reagle 编写了一个脚本，该脚本可以将 Pelican 的 front matter 转换为 Pandoc 的 YAML 标题格式。[转换脚本]

有关 Pandoc 的 YAML 元数据块或 Pelican 的默认元数据格式的更多信息，请访问以下链接

• Pandoc 的 YAML 元数据块
• Pelican 的默认元数据格式

指定 Pandoc 选项

插件支持两种 互斥 的方法来传递选项给 Pandoc。

方法一：通过 Pelican 设置

第一种方法涉及在您的 Pelican 设置文件（例如，pelicanconf.py）中配置两个设置

• PANDOC_ARGS
• PANDOC_EXTENSIONS

在 PANDOC_ARGS 设置中，您可以指定 Pandoc 支持的任何参数，如下所示

PANDOC_ARGS = [
    "--mathjax",
    "--citeproc",
]

在 PANDOC_EXTENSIONS 设置中，您可以启用/禁用任何支持的 Pandoc 扩展

PANDOC_EXTENSIONS = [
    "+footnotes",   # Enabled extension
    "-pipe_tables", # Disabled extension
]

方法二：使用 Pandoc 默认文件

第二种方法涉及指定一个或多个 Pandoc 默认文件 的路径，所有偏好都使用 YAML 格式编写。

这些路径应通过使用设置 PANDOC_DEFAULTS_FILES 在您的 Pelican 设置文件中设置。路径可以是绝对路径或相对路径，但建议使用相对路径，因为它们更便携。

PANDOC_DEFAULTS_FILES = [
    "<path/to/defaults/file_one.yaml>",
    "<path/to/defaults/file_two.yaml>",
]

以下是在 Pandoc 默认文件中应提供的最小示例内容

reader: markdown
writer: html5

使用默认文件的好处是允许您使用 Pandoc 支持的其他 Markdown 变体，例如 CommonMark 和 GitHub-Flavored Markdown。

有关更完整的示例，请参阅 Pandoc 默认文件。

⚠️ 注意： 两种方法都不支持 --standalone 或 --self-contained 参数，如果调用将产生错误。

生成目录

如果您想要为文章或页面创建目录（ToC），可以通过在PANDOC_ARGS设置中指定--toc或--table-of-contents参数来实现，如下所示

PANDOC_ARGS = [
    "--toc",
]

……或……

PANDOC_ARGS = [
    "--table-of-contents",
]

通过Pandoc默认文件添加目录，请使用以下语法

table-of-contents: true

目录将在模板中使用{{ article.toc }}或{{ page.toc }} Jinja模板变量可用。

启用引文

您可以通过指定-C或--citeproc选项来启用引文。

按照以下示例在您的Pelican设置文件中设置PANDOC_ARGS和PANDOC_EXTENSIONS

PANDOC_ARGS = [
    "--citeproc",
]

… 或者 …

PANDOC_ARGS = [
    "-C",
]

如果您正在使用Pandoc默认文件，您需要以下内容作为启用引文的最低要求

reader: markdown
writer: html5

citeproc: true

没有这些设置，插件将不会处理引文。

不需要指定+citations扩展，因为它默认启用。但是，如果您通过在PANDOC_EXTENSIONS中指定-citations或在默认文件中设置reader: markdown-citations来禁用引文，引文将不会工作。

您可以使用Pandoc支持的任何格式编写参考文献，但必须指定适当的扩展。然而，您必须将参考文献文件命名为与您的文章相同的名称。

例如，文件名为my-post.md的文章应该在同一目录或博客所在目录的子目录中有一个名为my-post.bib、my-post.json、my-post.yaml或my-post.bibtex的参考文献文件。否则，引用将无法被选中。

关于引文的已知问题

如果您要启用具有特定样式的引文，需要指定一个CSL（引文样式语言）文件，该文件可从Zotero样式存储库获取。例如，如果您正在使用ieee-with-url样式文件，它可以在您的Pelican设置文件中指定，如下所示

PANDOC_ARGS = [
   "--csl=https://www.zotero.org/styles/ieee-with-url",
]

或者在Pandoc默认文件中

csl: "https://www.zotero.org/styles/ieee-with-url"

如上所示，指定一个远程（即非本地）的CSL文件将显著增加处理Markdown内容所需的时间。为了提高处理速度，强烈建议您使用从Zotero下载的CSL文件的本地副本。

然后您可以在Pelican设置文件中按照以下示例引用它

PANDOC_ARGS = [
   "--csl=path/to/file/ieee-with-url.csl",
]

或者在Pandoc默认文件中

csl: "path/to/file/ieee-with-url.csl"

计算和显示阅读时间

可以通过在Pelican设置文件中将CALCULATE_READING_TIME设置为True来使用此插件计算文章和页面的预估阅读时间

CALCULATE_READING_TIME = True

您可以使用{{ article.reading_time }}或{{ page.reading_time }}模板变量显示预估阅读时间。时间单位将显示为“分钟”对于小于或等于一分钟的阅读时间，或对于大于一分钟的阅读时间显示为“分钟”。

阅读时间是通过将单词数除以阅读速度来计算的，阅读速度是每分钟平均阅读的单词数。

默认的阅读速度设置为每分钟200个单词，但您可以通过在Pelican设置文件中将READING_SPEED设置为所需的每分钟单词数来自定义它

READING_SPEED = <words-per-minute>

文档中的单词数使用wordcount Lua Filter来计算。

自定义pandoc可执行文件的路径

如果您的pandoc可执行文件不在您的PATH中，请将Pelican设置文件中的PANDOC_EXECUTABLE_PATH设置为pandoc所在位置的绝对路径，如下所示

PANDOC_EXECUTABLE_PATH = /path/to/my/pandoc

此设置在以下情况下很有用：您的托管提供商的pandoc可执行文件版本不够新，您可能需要在非标准位置安装与该插件兼容的Pandoc版本。

贡献

欢迎并非常感谢大家的贡献。每一份努力都至关重要。您可以通过改进文档、添加缺失的功能和修复错误来做出贡献。您还可以通过审查和评论现有问题来提供帮助。

要开始为这个插件做出贡献，请阅读为Pelican做出贡献文档，从《贡献代码》部分开始。

特别感谢Justin Mayer、Erwin Janssen、Joseph Reagle和Deniz Turgut对这一插件的改进和反馈。

许可

本项目采用AGPL-3.0许可协议。