一个使用BibTeX管理引用的MkDocs插件
项目描述
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=bibtexbib_dir- 加载bibtex文件的目录，路径解析方式与上述相同bib_command- 渲染参考文献的语法，默认为\bibliographybib_by_default- 在每个Markdown文档末尾自动附加bib_command，默认为truefull_bib_command- 渲染整个参考文献的语法，默认为\full_bibliographycsl_file- bibtex CSL文件的路径或URL，指定您的引用格式。默认为None，以纯文本格式渲染。引用样式注册表可以在以下位置找到： https://github.com/citation-style-language/stylescite_inline- 是否在行内渲染引用，需要指定csl_file。默认为False。
使用方法
在您的Markdown文件中
- 添加引用，就像使用 pandoc 一样，例如：
[@first_cite;@second_cite] - 将
\bibliography或bib_command的值添加到您希望显示引用的文档中（如果bib_by_default设置为 true，则自动应用于每一页）。 - （可选）将
\full_bibliography或full_bib_command的值添加到您希望显示完整参考文献的地方。 注意：由于此插件无法指定文件处理的顺序，因此目前无法正常工作。确保包含完整参考文献的文件最后处理的最佳方法是使用数字在文件/文件夹名前强制处理顺序，例如：01_my_first_file.md - （可选）配置
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
