Skip to main content

An MkDocs plugin that enables managing citations with BibTex

Project description

THIS IS NO LONGER MAINTAINED OR UPDATED

testing codecov Language grade: Python

mkdocs-bibtex

A MkDocs plugin for citation management using bibtex.

Setup

Install the plugin using pip:

pip install mkdocs-bibtex

Note: This plugin requires pandoc to be installed on your system.
If you're having trouble with pandoc, try installing the conda-forge version of pypandoc: conda install -c conda-forge pypandoc which will install a version with built in pandoc binaries

Next, add the following lines to your mkdocs.yml:

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

The footnotes extension is how citations are linked for now.

If you have no plugins entry in your config file yet, you'll likely also want to add the search plugin. MkDocs enables it by default if there is no plugins entry set.

Options

  • bib_file - The path or url to a single bibtex file. Path can either be absolute or relative to mkdocs.yml. Example URL: https://api.zotero.org/*/items?format=bibtex
  • bib_dir - Directory for bibtex files to load, same as above for path resolution
  • bib_command - The syntax to render your bibliography, defaults to \bibliography
  • bib_by_default - Automatically append the bib_command at the end of every markdown document, defaults to true
  • full_bib_command - The syntax to render your entire bibliography, defaults to \full_bibliography
  • footnote_format - The footnote key formatting template. Must contain the {key} substring.
  • csl_file - The path or url to a bibtex CSL file, specifying your citation format. Defaults to None, which renders in a plain format. A registry of citation styles can be found here: https://github.com/citation-style-language/styles
  • csl_file_encoding - The csl file encoding. Defaults to None, which uses the platform encoding defaults. Note the remote (URL-based) CSL files are temporarily written using the utf-8 encoding.
  • enable_inline_citations - enable inline citations, defaults to true

Usage

In your markdown files:

  1. Add your citations as you would if you used pandoc, IE: [@first_cite;@second_cite]. If you want to have a direct reference in your docs, you can write an inline citation the same way pandoc would expect it. @my_inline_citation
  2. Add \bibliography, or the value of bib_command, to the doc you want your references rendered (if bib_by_default is set to true this is automatically applied for every page).
  3. (Optional) Add \full_bibliography, or the value of full_bib_command, to where you want the full bibliography rendered. Note: This is currently not working properly, since this plugin can't dictate the order in which files are processed. The best way to ensure the file with the full bibliography gets processed last is to use numbers in front of file/folder names to enforce the order of processing, IE: 01_my_first_file.md
  4. (Optional) Configure the csl_file option to dictate the citation text formatting. This plugin automatically detects if the citation is an inline style and inserts that text when appropriate.

Debugging

You can run mkdocs with the --strict flag to fail building on any citations that don't exist in the bibtex file.

You may wish to use the verbose flag in mkdocs (-v) to log debug messages. You should see something like this

(...)
DEBUG   -  Reading markdown pages.
DEBUG   -  Reading: index.md
DEBUG   -  Running `page_markdown` event from plugin 'bibtex'
WARNING -  Citing unknown reference key nonexistent
DEBUG   -  Converting with pandoc:
DEBUG   -   ---
           link-citations: false
           ---

           0. [@test]

           1. [@nonexistent]

           2. [@test, see pp. 100]

           3. [see @test, pp. 100, 200]

           # References

[WARNING] Citeproc: citation nonexistent not found

DEBUG   -  Pandoc output:
DEBUG   -  0.  ^1^

           1.  ^**nonexistent?**^

           2.  ^1,\ see\ pp. 100^

           3.  ^see\ 1^

           # References {#references .unnumbered}

           :::: {#refs .references .csl-bib-body entry-spacing="0" line-spacing="2"}
           ::: {#ref-test .csl-entry}
           [1. ]{.csl-left-margin}[Author, F. & Author, S. Test title. *Testing
           Journal* **1**, (2019).]{.csl-right-inline}
           :::
           ::::
DEBUG   -  Inline cache: {'[@test]': '^1^', '[@nonexistent]': '^**nonexistent?**^', '[@test, see pp. 100]': '^1,\\ see\\ pp. 100^', '[see @test, pp. 100, 200]': '^see\\ 1^'}
DEBUG   -  Reference cache: {'test': 'Author, F. & Author, S. Test title. *Testing Journal* **1**, (2019).'}
WARNING -  Error formatting citation nonexistent: 'nonexistent'
DEBUG   -  Markdown:
           # This is an example of how to use the mkdocs-bibtex plugin

           ## Citation

           Citation [^test]

           ## Non existing citation

           This should fail on --strict mode

           Citation

           ## Citation with affix

           Citation [^test]

           ## Citation with multiple affixes

           Citation [^test]


           ## Bibliography

           [^test]: Author, F. & Author, S. Test title. *Testing Journal* **1**, (2019).
DEBUG   -  Reading: full_bib.md
(...)

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mkdocs_bibtex-4.3.0.tar.gz (34.9 kB view details)

Uploaded Source

Built Distribution

mkdocs_bibtex-4.3.0-py3-none-any.whl (14.5 kB view details)

Uploaded Python 3

File details

Details for the file mkdocs_bibtex-4.3.0.tar.gz.

File metadata

  • Download URL: mkdocs_bibtex-4.3.0.tar.gz
  • Upload date:
  • Size: 34.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for mkdocs_bibtex-4.3.0.tar.gz
Algorithm Hash digest
SHA256 1861e73d4a26c5a9dbfec827ca4a9de8ab16da989f255605870871f1f4f05b10
MD5 17dc7f5b54921597b9d7f61cb949bdda
BLAKE2b-256 54d0a961fc6b9cc9973cea9ed367588b3ce927d292f35631a9fd54ae76e67326

See more details on using hashes here.

File details

Details for the file mkdocs_bibtex-4.3.0-py3-none-any.whl.

File metadata

  • Download URL: mkdocs_bibtex-4.3.0-py3-none-any.whl
  • Upload date:
  • Size: 14.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.12.9

File hashes

Hashes for mkdocs_bibtex-4.3.0-py3-none-any.whl
Algorithm Hash digest
SHA256 07b6cd5451cc3f510994c1b26ab25b76327d9479b2f07a213a53490bc355b215
MD5 8716f770b83004cda4a6283cbf9daa47
BLAKE2b-256 2fbcf675cd7c42b5a213fd916cd37cedfe05a968620dc4bff1e114a02e6fd828

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page