文献综述：Pelican插件

在Pelican中生成可渲染为参考文献和引用的文献综述

此插件提供了一种新的生成器，BibliographyGenerator。此生成器将bibliography添加到Pelican上下文中，并可以使用citation.html模板为每个参考文献写入输出文件。此外，整个文献综述也可以使用bibliography.html模板或其他方式写入。

安装

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

pip install pelican-bibliography

现在，将其添加到您的pelicanconf.py

PLUGINS = ['pelican.plugins.bibliography']

就是这样，感谢Pelican 4.5+中的命名空间插件。

使用方法

当运行此生成器时，它首先从BIBLIOGRAPHY_PATHS设置中读取参考文献文件。目前只支持BibTeX（.bib）文件，但未来可能会添加更多。参考文献集中的每个参考文献都实例化为一个Reference对象。参考文献的内容是其bibtex中的引用，而大部分有用信息都在元数据中，例如引用键、标题、作者、发表地点。可以从同一参考文献路径中的YAML文件中读取额外的元数据键值对。现在，您可以在模板中使用bibliography。

接下来，可以将引用写入单独的文件。如果需要，对于每个参考文献，将根据citation.html模板渲染引用并写入配置的路径。理想情况下，您的参考文献将链接到引用页面，以便感兴趣的读者可以轻松引用您的作品。

配置

以下变量可以在您的pelicanconf.py中进行配置

# A directory that contains the bibliography-related templates
# type: Union[str, os.PathLike]
BIBLIOGRAPHY_TEMPLATES = '.../pelican/plugins/bibliography/data/templates'

# A list of directories and files to look at for bibliographies, relative
# to PATH.
# type: List[str]
BIBLIOGRAPHY_PATHS = ["bibliography"]

# A list of directories to exclude when looking for references
# type: List[str]
BIBLIOGRAPHY_EXCLUDES = []

# list of file extensions (without leading period) that are bibliography
# files
# type: List[str]
BIBLIOGRAPHY_EXTENSIONS = ["bib"]

# list of file extensions (without leading period) that are metadata files
# type: List[str]
BIBLIOGRAPHY_METADATA_EXTENSIONS = ["yml", "yaml"]

# attribute of the Reference object to order the bibliography by (in
# reverse order)
# type: str
BIBLIOGRAPHY_ORDER_BY = "sortkey"

# whether to write citations to files
# type: bool
BIBLIOGRAPHY_WRITE_CITATIONS = True

# template to use for citations
# type: str
BIBLIOGRAPHY_CITATION_TEMPLATE_NAME = "citation.html"

# format string to link to citation
# type: str
BIBLIOGRAPHY_CITATION_URL = "files/citation/{key}"

# format string to save citations as in generated site
# type: str
BIBLIOGRAPHY_CITATION_SAVE_AS = "files/citation/{key}/index.html"

参考文献页面

此应用的主要用途之一是创建一个显示某些已发表论文集合的研究页面。例如，您可以在主题中创建一个新的模板，bibliography.html，以渲染您的科研内容

Here are the titles of my papers:
<ul>
    {% for ref in bibliography %}
    <li>{{ ref.title }}</li>
    {% endfor %}
</ul>

您不能仅将参考文献放在网站的content/中，因为当读取内容时，包含文章、页面、参考文献等的上下文不可用。您可以创建一个新的模板，扩展page.html或article.html，并使用该模板在内容树中渲染一些文本。

插件附带的基本参考文献模板试图扩展您的主题页面模板。因此，您可以通过将此页面添加到内容中来渲染参考文献

Title: My Bibliography
Template: bibliography

Here is my bibliography

查看使用提供的模板的示例参考文献。

额外元数据

您还可以在具有以下结构的YAML文件中提供额外的元数据

- key: someCitationKey2020
  metadata:
    key1: value1
    key2: value2

现在，与引用键关联的元数据哈希中的键和值将可在bibliography中的相应ref.metadata字典中找到。

参考文献模板

包中包含的默认bibliography.html模板有自己的跳转链接和突出显示样式。您可以自定义其他元素。例如，为了样式特定的作者

.ref-author[data-given="Micah J."][data-family="Smith"] {
    text-weight: bold;
}

您可以使用多个选择器来应用样式到具有与特定名称匹配的数据属性的ref-author span。

该模板还支持为每个项目渲染链接。在元数据文件中添加一个键links，它是一个包含键href和icon的哈希列表，即

- key: someCitationKey2020
  metadata:
    links:
      - href: https://www.example.com
        icon: link

现在将包含一个链接到指定网站的图标。确切的图标由fa-{link.icon}决定，因此fa-link是一个链接，icon: file-pdf将链接到fa-file-pdf等。

贡献

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

要开始为这个插件做出贡献，请查看为Pelican做出贡献的文档，从贡献代码部分开始。

许可协议

本项目采用MIT许可协议。