[](https://github.com/shyamd/mkdocs-bibtex/actions?query=workflow%3Atesting)
[](https://codecov.io/gh/shyamd/mkdocs-bibtex)
[](https://lgtm.com/projects/g/shyamd/mkdocs-bibtex/context:python)
# mkdocs-bibtex
A [MkDocs](https://www.mkdocs.org/) 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.<br>
> 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`:
```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
## 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. 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
```bash
(...)
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
(...)
```
Raw data
{
"_id": null,
"home_page": null,
"name": "mkdocs-bibtex",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "mkdocs, python, markdown, bibtex",
"author": null,
"author_email": "Shyam Dwaraknath <16827130+shyamd@users.noreply.github.com>",
"download_url": "https://files.pythonhosted.org/packages/70/d3/8728e6d84527204bbac2d85f63bf5d975518a46b03552e333921e870303c/mkdocs_bibtex-4.1.0.tar.gz",
"platform": null,
"description": "[](https://github.com/shyamd/mkdocs-bibtex/actions?query=workflow%3Atesting)\n[](https://codecov.io/gh/shyamd/mkdocs-bibtex)\n[](https://lgtm.com/projects/g/shyamd/mkdocs-bibtex/context:python)\n\n# mkdocs-bibtex\n\nA [MkDocs](https://www.mkdocs.org/) plugin for citation management using bibtex.\n\n## Setup\n\nInstall the plugin using pip:\n\n```\npip install mkdocs-bibtex\n```\n> *Note:* This plugin requires pandoc to be installed on your system.<br>\n> 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\n\n\nNext, add the following lines to your `mkdocs.yml`:\n\n```yml\nplugins:\n - search\n - bibtex:\n bib_file: \"refs.bib\"\nmarkdown_extensions:\n - footnotes\n```\n\nThe footnotes extension is how citations are linked for now.\n\n> 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.\n\n## Options\n\n- `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`\n- `bib_dir` - Directory for bibtex files to load, same as above for path resolution\n- `bib_command` - The syntax to render your bibliography, defaults to `\\bibliography`\n- `bib_by_default` - Automatically append the `bib_command` at the end of every markdown document, defaults to `true`\n- `full_bib_command` - The syntax to render your entire bibliography, defaults to `\\full_bibliography`\n- `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\n\n## Usage\n\nIn your markdown files:\n\n1. Add your citations as you would if you used pandoc, IE: `[@first_cite;@second_cite]`.\n2. 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).\n3. (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`\n4. (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.\n\n## Debugging\n\nYou can run mkdocs with the `--strict` flag to fail building on any citations that don't exist in the bibtex file.\n\nYou may wish to use the verbose flag in mkdocs (`-v`) to log debug messages. You should see something like this\n\n```bash\n(...)\nDEBUG - Reading markdown pages.\nDEBUG - Reading: index.md\nDEBUG - Running `page_markdown` event from plugin 'bibtex'\nWARNING - Citing unknown reference key nonexistent\nDEBUG - Converting with pandoc:\nDEBUG - ---\n link-citations: false\n ---\n\n 0. [@test]\n\n 1. [@nonexistent]\n\n 2. [@test, see pp. 100]\n\n 3. [see @test, pp. 100, 200]\n\n # References\n\n[WARNING] Citeproc: citation nonexistent not found\n\nDEBUG - Pandoc output:\nDEBUG - 0. ^1^\n\n 1. ^**nonexistent?**^\n\n 2. ^1,\\ see\\ pp. 100^\n\n 3. ^see\\ 1^\n\n # References {#references .unnumbered}\n\n :::: {#refs .references .csl-bib-body entry-spacing=\"0\" line-spacing=\"2\"}\n ::: {#ref-test .csl-entry}\n [1. ]{.csl-left-margin}[Author, F. & Author, S. Test title. *Testing\n Journal* **1**, (2019).]{.csl-right-inline}\n :::\n ::::\nDEBUG - Inline cache: {'[@test]': '^1^', '[@nonexistent]': '^**nonexistent?**^', '[@test, see pp. 100]': '^1,\\\\ see\\\\ pp. 100^', '[see @test, pp. 100, 200]': '^see\\\\ 1^'}\nDEBUG - Reference cache: {'test': 'Author, F. & Author, S. Test title. *Testing Journal* **1**, (2019).'}\nWARNING - Error formatting citation nonexistent: 'nonexistent'\nDEBUG - Markdown:\n # This is an example of how to use the mkdocs-bibtex plugin\n\n ## Citation\n\n Citation [^test]\n\n ## Non existing citation\n\n This should fail on --strict mode\n\n Citation\n\n ## Citation with affix\n\n Citation [^test]\n\n ## Citation with multiple affixes\n\n Citation [^test]\n\n\n ## Bibliography\n\n [^test]: Author, F. & Author, S. Test title. *Testing Journal* **1**, (2019).\nDEBUG - Reading: full_bib.md\n(...)\n```\n",
"bugtrack_url": null,
"license": "BSD-3-Clause-LBNL",
"summary": "An MkDocs plugin that enables managing citations with BibTex",
"version": "4.1.0",
"project_urls": {
"Homepage": "https://github.com/shyamd/mkdocs-bibtex/"
},
"split_keywords": [
"mkdocs",
" python",
" markdown",
" bibtex"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "89fe7effd68f45a8fe708c33670c8b3a8f5b8fed2e303ae0284e6e2f86268d7f",
"md5": "66f15371746c51683228d15746579d67",
"sha256": "7d59aa5eb8023b64a632ee2681af38a3001e4de541805fa45fb8d81817b67fbc"
},
"downloads": -1,
"filename": "mkdocs_bibtex-4.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "66f15371746c51683228d15746579d67",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 13690,
"upload_time": "2025-01-26T01:10:05",
"upload_time_iso_8601": "2025-01-26T01:10:05.972237Z",
"url": "https://files.pythonhosted.org/packages/89/fe/7effd68f45a8fe708c33670c8b3a8f5b8fed2e303ae0284e6e2f86268d7f/mkdocs_bibtex-4.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "70d38728e6d84527204bbac2d85f63bf5d975518a46b03552e333921e870303c",
"md5": "8828d430165b72248549f3d5521d23c9",
"sha256": "3afe45a8c4ed654d42700db5d9fc283fe8aae1c7b16f384c22b4db150add5dd1"
},
"downloads": -1,
"filename": "mkdocs_bibtex-4.1.0.tar.gz",
"has_sig": false,
"md5_digest": "8828d430165b72248549f3d5521d23c9",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 31631,
"upload_time": "2025-01-26T01:10:07",
"upload_time_iso_8601": "2025-01-26T01:10:07.056876Z",
"url": "https://files.pythonhosted.org/packages/70/d3/8728e6d84527204bbac2d85f63bf5d975518a46b03552e333921e870303c/mkdocs_bibtex-4.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-26 01:10:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "shyamd",
"github_project": "mkdocs-bibtex",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"requirements": [
{
"name": "mkdocs",
"specs": [
[
"==",
"1.6.1"
]
]
},
{
"name": "pybtex",
"specs": [
[
"==",
"0.24.0"
]
]
},
{
"name": "pypandoc",
"specs": [
[
"==",
"1.14"
]
]
},
{
"name": "requests",
"specs": [
[
"==",
"2.32.3"
]
]
},
{
"name": "validators",
"specs": [
[
"==",
"0.34.0"
]
]
},
{
"name": "responses",
"specs": [
[
"==",
"0.25.6"
]
]
}
],
"lcname": "mkdocs-bibtex"
}
JSON
