Skip to main content

An MkDocs plugin that enables managing citations with BibTex

Project description

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
  • 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
  • cite_inline - Whether or not to render citations inline, requires csl_file to be specified. Defaults to False.

Usage

In your markdown files:

  1. Add your citations as you would if you used pandoc, IE: [@first_cite;@second_cite]
  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.

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-recursive-2.8.15.tar.gz (18.6 kB view details)

Uploaded Source

Built Distribution

mkdocs_bibtex_recursive-2.8.15-py3-none-any.whl (10.3 kB view details)

Uploaded Python 3

File details

Details for the file mkdocs-bibtex-recursive-2.8.15.tar.gz.

File metadata

File hashes

Hashes for mkdocs-bibtex-recursive-2.8.15.tar.gz
Algorithm Hash digest
SHA256 196dd8d72e3c8614cfb84862604f3dea487775d1dddd7bf1896f6c70cfb3848b
MD5 a3903c5d89a2c750a4617eaa65c4b0f3
BLAKE2b-256 1008b1e92731c277b78953feaea1811e70f2287a84bdab7bfa17d3389340f208

See more details on using hashes here.

File details

Details for the file mkdocs_bibtex_recursive-2.8.15-py3-none-any.whl.

File metadata

File hashes

Hashes for mkdocs_bibtex_recursive-2.8.15-py3-none-any.whl
Algorithm Hash digest
SHA256 639c4617decdc77bb1d3f8bc8314aa7bb5f35f519ece7b5d379d6ba42d5e2850
MD5 f8072ddd3647c11c951db2a79f7bc4ed
BLAKE2b-256 e5e1a3d23ed92fce6010e7ba2278534fccbb25d2e6f109a9032535881249353d

See more details on using hashes here.

Supported by

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