跳转到主要内容

一个使用BibTeX管理引用的MkDocs插件

项目描述

testing codecov Language grade: Python

mkdocs-bibtex

MkDocs的一个插件,用于使用bibtex进行引用管理。

安装

使用pip安装插件

pip install mkdocs-bibtex

注意: 此插件需要在您的系统上安装pandoc。
如果您在使用pandoc时遇到问题,请尝试安装conda-forge版本的pypandoc: conda install -c conda-forge pypandoc,这将安装一个内置pandoc二进制的版本

接下来,将以下行添加到您的 mkdocs.yml

plugins:
  - search
  - bibtex:
      bib_file: "refs.bib"
markdown_extensions:
  - footnotes

脚注扩展是当前引用链接的方式。

如果您在配置文件中还没有plugins条目,您可能还想要添加search插件。如果没有设置plugins条目,MkDocs默认启用它。

选项

  • bib_file - 单个bibtex文件的路径或URL。路径可以是绝对路径,也可以是相对于mkdocs.yml的相对路径。示例URL: https://api.zotero.org/*/items?format=bibtex
  • bib_dir - 加载bibtex文件的目录,路径解析方式与上述相同
  • bib_command - 渲染参考文献的语法,默认为\bibliography
  • bib_by_default - 在每个Markdown文档末尾自动附加bib_command,默认为true
  • full_bib_command - 渲染整个参考文献的语法,默认为\full_bibliography
  • csl_file - bibtex CSL文件的路径或URL,指定您的引用格式。默认为None,以纯文本格式渲染。引用样式注册表可以在以下位置找到: https://github.com/citation-style-language/styles
  • cite_inline - 是否在行内渲染引用,需要指定csl_file。默认为False

使用方法

在您的Markdown文件中

  1. 添加引用,就像使用 pandoc 一样,例如:[@first_cite;@second_cite]
  2. \bibliographybib_command 的值添加到您希望显示引用的文档中(如果 bib_by_default 设置为 true,则自动应用于每一页)。
  3. (可选)将 \full_bibliographyfull_bib_command 的值添加到您希望显示完整参考文献的地方。 注意:由于此插件无法指定文件处理的顺序,因此目前无法正常工作。确保包含完整参考文献的文件最后处理的最佳方法是使用数字在文件/文件夹名前强制处理顺序,例如:01_my_first_file.md
  4. (可选)配置 csl_file 选项以指定引用文本的格式。

调试

您可能希望在 mkdocs 中使用详细标志(-v)来记录调试信息。您应该看到类似以下内容:

(...)
DEBUG   -  Parsing bibtex file 'docs/bib/papers.bib'...
INFO    -  SUCCESS Parsing bibtex file 'docs/bib/papers.bib'
DEBUG   -  Downloading CSL file from URL https://raw.githubusercontent.com/citation-style-language/styles/master/apa-6th-edition.csl to temporary file...
INFO    -  CSL file downladed from URL https://raw.githubusercontent.com/citation-style-language/styles/master/apa-6th-edition.csl to temporary file (<tempfile._TemporaryFileWrapper object at 0x00000203E4F2F650>)
(...)
DEBUG   -  Reading: publications.md
DEBUG   -  Running 2 `page_markdown` events
DEBUG   -  Formatting all bib entries...
DEBUG   -  --Converting bibtex entry 'foo2019' with CSL file 'docs/bib/apa_verbose.csl' using pandoc>=2.11
DEBUG   -  --SUCCESS Converting bibtex entry 'foo2019' with CSL file 'docs/bib/apa_verbose.csl' using pandoc>=2.11
DEBUG   -  --Converting bibtex entry 'bar2024' with CSL file 'docs/bib/apa_verbose.csl' using pandoc>=2.11
DEBUG   -  --SUCCESS Converting bibtex entry 'bar2024' with CSL file 'docs/bib/apa_verbose.csl' using pandoc>=2.11
INFO    -  SUCCESS Formatting all bib entries
DEBUG   -  Replacing citation keys with the generated ones...
DEBUG   -  --Rendering citation inline for '[@foo2019]'...
DEBUG   -  ----Converting pandoc citation key '[@foo2019]' with CSL file 'docs/bib/apa_verbose.csl' and Bibliography file '(...)/tmpzt7t8p0y/temp.bib'...
DEBUG   -  ----SUCCESS Converting pandoc citation key '[@foo2019]' with CSL file 'docs/bib/apa_verbose.csl' and Bibliography file '(...)/tmpzt7t8p0y/temp.bib'
DEBUG   -  --SUCCESS Rendering citation inline for '[@foo2019]'
DEBUG   -  --Rendering citation inline for '[@bar2024]'...
DEBUG   -  ----Converting pandoc citation key '[@bar2024]' with CSL file 'docs/bib/apa_verbose.csl' and Bibliography file '(...)/tmpzt7t8p0y/temp.bib'...
DEBUG   -  ----SUCCESS Converting pandoc citation key '[@bar2024]' with CSL file 'docs/bib/apa_verbose.csl' and Bibliography file '(...)/tmpzt7t8p0y/temp.bib'
DEBUG   -  --SUCCESS Rendering citation inline for '[@bar2024]'
DEBUG   -  SUCCESS Replacing citation keys with the generated ones

项目详情


下载文件

下载您平台上的文件。如果您不确定选择哪个,请了解更多关于 安装包 的信息。

源分布

mkdocs-bibtex-2.16.2.tar.gz (21.8 kB 查看哈希)

上传时间

构建分布

mkdocs_bibtex-2.16.2-py3-none-any.whl (11.6 kB 查看哈希)

上传时间 Python 3

支持者

AWS AWS 云计算和安全赞助商 Datadog Datadog 监控 Fastly Fastly CDN Google Google 下载分析 Microsoft Microsoft PSF 赞助商 Pingdom Pingdom 监控 Sentry Sentry 错误记录 StatusPage StatusPage 状态页面