shyamd / mkdocs-bibtex Goto Github PK

View Code? Open in Web Editor NEW

67.0 67.0 18.0 283 KB

A MkDocs plugin for citation management using bibtex

License: Other

Python 94.45% TeX 5.55%

mkdocs-bibtex's People

Contributors

Stargazers

Watchers

Forkers

timvink marcofavorito alexvoronov fadhleryani ju-mueller 1one-w01f roaldarbol epogrebnyak sondregronas centaurioun daylinmorgan kotval thomzoy sdruskat smarie evan-flynn-apexai haiiliin mdbenito

mkdocs-bibtex's Issues

Citations being cut off

Continuing the discussion from #72
It seems the pandoc parsing is causing some references to get cut off if the citation or the style inserts new lines (\n)

@roaldarbol can you provide a BibTeX entry that fails? I'd like to have that in the tests to ensure the correct behavior is being reproduced.

UTF-8 Encoding errors with pandoc due to temporary files being written in ASCII encoding

Hi there, thanks a lot for this great package !

I ran into several encoding errors with the same message:

RuntimeError: Pandoc died with exitcode "1" during conversion: pandoc: Cannot decode byte '\xe9': Data.Text.Internal.Encoding.decodeUtf8: Invalid UTF-8 stream

After digging a little bit it seems that the cause is with the temporary files created by mkdocs-bibtex before calling pandoc. These are encoded in default encoding (which turns out to be ascii at least on my machine), while pypandoc.convert_text's documentation states convert_text expects this string to be unicode or utf-8 encoded bytes., at least for input strings but also it seems, for CSL and bibliography files.

mkdocs-bibtex does not render citations where a period (.) exists in the key

When rendering a site with mkdocs using the mkdocs-bibtex plugin, citations are not recognised if they have a period within the citation key.

I tried a minimum working example and could reproduce the behaviour. To reproduce the behaviour, set up a folder containing the files below and run the command mkdocs serve. The browser should render both citations correctly but it only functions as expected for the citation key without the period.

MWE

Site structure:

MWE
- docs
  - index.md
- mkdocs.yml
- mwe.bib

index.md

# Home

Blah blah [@Jarse2023]. 

Woof woof [@Jarse.2023]

mkdocs.yml

site_name: MWE
docs_dir: docs
site_dir: site

plugins: 
  - search
  - bibtex:
      bib_file: mwe.bib

markdown_extensions:
  - footnotes

mwe.bib

@article{Jarse2023,
author = {Jarse, Hugh},
journal = {Beano},
title = {{The width of seats on urban public transport}},
year = {2023}
}
@article{Jarse.2023,
author = {Jarse, Hugh},
journal = {Beano},
title = {{The width of seats on urban public transport}},
year = {2023}
}

bug: refactor tests

Chasing down #170 is turning out to be a bit of pain since the tests are on giant jumble. I should refactor them to make this easier in the future.

Add deploy

Should auto-deploy to PyPi

Make the logging less verbose

I get this for instance:

INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries
INFO    -  SUCCESS Formatting all bib entries

Would it be possible to only have log message for warning and errors instead?

Default footnotes ignore/overwrite existing footnotes

I sometimes use a simple numbering scheme with footnotes i.e. [^1][^2].

If a document already uses footnotes then the plugin will happily override them.

A simple solution may be to namespace the footnotes to make this less likely and add this info to the README.

For example

[^1-citation]: ....

[^ref1]: .....

Or perhaps exposing this a user configurable option and defaulting to the existing behavior.

plugins:
  - search
  - bibtex:
      bib_file: "refs.bib"
      footnote_format: "ref{number}"
markdown_extensions:
  - footnotes

I can submit a PR if this makes sense.

pandoc-citeproc deprecated

Hi there, thanks for a great plugin! I just updated my pandoc, and now I'm getting an error message trying to mkdocs serve:

RuntimeError: Pandoc died with exitcode "83" during conversion: b'[WARNING] Deprecated: pandoc-citeproc filter. Use --citeproc instead.\nError running filter pandoc-citeproc:\nCould not find executable pandoc-citeproc\n'

It seeems to be caused by line 212 in plugin.py which specifies filters=["pandoc-citeproc"]. Importantly, pandoc-citeproc can no longer be downloaded with homebrew on Mac, so a new solution seems to be needed. I've tried a few things, and it seems that the fix is to remove filters and add --citeproc to extra_args instead. I'll try to do a pull request (it'll be my first, so I need to learn that now ;-) ).

Extra regex artefact in formatted output

When csl file is defined, footnote citations are rendered with what looks like extra characters perhaps left over from regex operations.

Expected output (get this with no csl_file defined)

Richard P. Feynman, Robert B. Leighton, and Matthew Sands. The Feynman Lectures on Physics. Addison-Wesley, Reading, MA, 1963. URL: http://www.feynmanlectures.caltech.edu/.

Obtained output (if csl_file is defined)

Feynman, R. P., Leighton, R. B., & Sands, M. (1963). [The Feynman Lectures on Physics]{.nocase}. Addison-Wesley. http://www.feynmanlectures.caltech.edu/.

Notice the extra square brackets around the document title, followed immediately by {.nocase}.

I'd like to use an external csl file and cite_inline which requires csl_file to be defined. Any ideas? Thanks.

Possibility to insert a bibliography item inline, with footnote reference disabled (=manual bibliography with generated style)

Hi, thanks a lot again for this plugin ! I am trying to use it to create a simple publications page for my personal website. Basically I would just like to create a page with a few sections, and insert in each section a bullet list with bibliographic items styled correctly leveraging pandoc + CSL.

I cannot manage to get it work because

if I do not cite anything from the .bib file, nothing is added into the generated markdown.
if I cite them, the generateg markdown is entirely managed by mkdocs-bibtex and therefore cannot be organized by type (journal, conferences, etc.). Plus, the citation has to go somewhere.

The current workaround I found is

to create a local copy of the APA style and edit the <citation> entry so that it is identical to <bibliography> (ugly !)
to set bib_by_default=false

Still, the result is not ideal. Indeed bib_by_default=false still inserts the footnotes references [^1], and since the bib is not generated they hang here in the resulting page

I see two features to create to get to something working:

adding a config option, or better a markdown hint, to tell mkdocs-bibtex that a specific citation key should be rendered inline using the "bibliography" style and not the "citation" style. For example [@foo2019] could be transformed as [@foo2019|b] where | denotes advanced options, and b denotes bibliography style.
adding a config option, or better a markdown hint as above, to tell mkdocs-bibtex to skip adding the markdown footnote [^1].

The combination of these two options would be reaching my objective, which is to insert at any place in the markdown document, an inlined bibliography item with the styling done by pandoc.

If you are ok with the above two features, I can make a pull request.

Change inline citation style

Is it possible to modify the inline citation style? Mine shows up as [^1], but according to the .csl styles they should be author-date? (moved from #72)

page numbers in references

Hi,

I am not sure if it is possible to add page numbers to the references and, if so, what the syntax would be? I tried [@favouriteAuthor2021xx p.123] but no luck. Also not sure how this would be rendered with the default citation style based on footnotes? (The page number could go into the footnote, I guess). In addition to page numbers might also want to reference chapters.

If not possible, please consider this a feature request.

Cheers, Alex

Duplicate entries in bibliography and footnotes

I am not sure what is causing this, but I updated to the latest mkdocs-bibtex and I am seeing duplicate entries of references. Have a look here:
lbsn.vgiscience.org mkdocs material docs

If the same citation is references several times, it will appear the same number of times duplicates in the bibliography.

Here's our mkdocs.yml:

site_name: LBSN Structure
site_url: https://lbsn.vgiscience.org/
site_author: Alexander Dunkel, Marc Löchner, Filip Krumpe
copyright: CC BY 4.0, 2022 Alexander Dunkel, Marc Löchner, Filip Krumpe, vgiscience.org and contributors
site_dir: site

plugins:
  - search
  - git-revision-date-localized
  - minify:
      minify_html: true
  - bibtex:
      bib_file: 'docs/references.bib'
      csl_file: 'apa.csl'

theme:
    name: 'material'
    custom_dir: overrides/
    palette:
      primary: 'Light Blue' #43C3F5
      accent: 'Orange' #F8A610
    logo: 'img/logo-white.svg'
    favicon: 'img/favicon.png'
    features:
      - navigation.instant
      - navigation.expand
      - navigation.top

...

markdown_extensions:
  - markdown.extensions.codehilite:
      guess_lang: false
  - markdown_include.include:
      base_path: docs
  - admonition
  - codehilite
  - extra
  - tables
  - sane_lists
  - pymdownx.superfences
  - pymdownx.details
  - pymdownx.tabbed:
      alternate_style: true 
  - footnotes

Here is some more testing:

also happens with default csl_file (parameter set to none)
mkdocs 1.2.3 and mkdocs-material 8.2.5 (both latest), mkdocs-bibtex 2.0.2
also happens with the test files provided in this repository
as you can see in the exmaple docs above, there are ::: characters added beyond each bibliography ending. This is independent of the csl file uses. I don't know where these are coming from.
I have a feeling that this may be related to pandoc, or the way it is installed, or the version. Running pandoc 2.17.1.1 locally, installed with conda,
in Debian Docker I observe the same behavior (same pandoc version, but installed with *.deb)

File with STRINGS

Hi,

I really like this project. One feature I'm missing is the possibility to use a bib file containing abbreviations (@STRING). We use a file called "abbrevs.bib" containing definitions like @STRING{PRL = {Phys.~Rev.~Lett.}}. In a usual Latex file this is included first in \bibliography{...}. If I include the directory containing all bib files (including abbrevs.bib) in my mkdocs.yml this leads to the error

pybtex.database.input.bibtex.UndefinedMacro: undefined string in line 9: IntJBifurcatChaos

This problem still occurs if I rename abbrevs.bib to aaa.bib to make sure it is loaded first (there are files beginning with a number). What is the problem here?

Thanks,
Jan

`pybtex` fails on Python 3.12

Same issue in: mcmtroffaes/sphinxcontrib-bibtex#345

Upstream issue: https://bitbucket.org/pybtex-devs/pybtex/issues/169/replace-pkg_resources-with

Adding some logging for better debugging

It might be convenient to log a few messages in order to ease the debugging process.

Trying to use it with tox to build docs with refs - but no effect

Hi.

I just found your tool - looks great! However, when I try to build my MkDocs with tox I do not get any citations at all? Neither any errors...

This is the tox section:

[testenv:docs]
description = Run a development server for working on documentation
basepython = python3.7
deps = mkdocs
       mkdocs-bibtex
       mkdocs-material
       pymdown-extensions

And in my index.md I use it like so:

Some content [@MrScience:2011].

\bibliography

This is the relevant section in MkDocs.yml:

plugins:
    - search
    - bibtex:
        bib_file: "docs/selpapers.bib"
        cite_style: "pandoc"

Result:

I have the citation as-is in my document (als plain text) and no bibliography at the end...

Do I miss something here?

Cheers,
C

in-text references instead of footnotes?

I tried different CSL formats but they all seem to create footnotes. Is there a way to have the plugin create in-text references like (Author 2019) instead?

Minor incompatibility with pymdown.arithmatex

The pymdownx.arithmatex extension may inject some MathJax code into the \bibliography section resulting in some characters being rendered as inline LaTeX code.

Compatibility with mkdocs-jupyter

References in notebooks (mkdocs-jupyter) are not picked up.

Is there something about the order of notebook conversion and reference processing that could be done?

strange behavior - results in wrong inline numbering

I have paper.bib file like:

@book{PM18,
  author = {Pearl, Judea and Mackenzie, Dana},
  publisher = {Basic Books},
  title = {The Book of Why: The New Science of Cause and Effect},
  year = {2018},
  address = {New York}
}

@book{Hamilton,
  author = {Hamilton, James D.},
  publisher = {Princeton University Press},
  title = {Time Series Analysis},
  year = {1994},
}

and index.md as

# Citations

- Book of Why[@PM18]
- Time Series Analysis[@Hamilton]

\bibliography

but the resulting html is not quite right:

    Book of Why[1](file:///Q:/bib/site/index.html#fn:1)
    Time Series Analysis[^2]

    James D. Hamilton. Time Series Analysis. Princeton University Press, 1994. [↩](file:///Q:/bib/site/index.html#fnref:1)

What can be going wrong? I tried runnng mkdocs on bith Windows and WSL. Many thanks for clues.

bug: brittle tests due to Pandoc

A few tests that depend on Pandoc formatting appear to be really brittle. This could be because of side effects or just because of pandoc. Still not sure which.

Docs

Need to write some better docs explaining all the use cases.

Escape problem with python 3.10 and material theme (insiders version)

Hi,

I'm trying to use mkdocs-bibtex with latest theme "material" as insider version.

My mkdocs.yml

site_name: Les cahiers d'IDEES
theme:
  name: material
  logo: assets/logo.png
  language: fr
  palette:
    primary: white
    accent: blue

markdown_extensions:
  - footnotes

plugins:
  - blog
  - tags
  - meta
  - git-revision-date-localized
  - search
  - bibtex:
      bib_file: "docs/bib/notebooks.bib"
      cite_style: "pandoc"
      bib_by_default: true

I have an espace error during compilation :

$ mkdocs build -v -f mkdocs-ci.yml
DEBUG   -  Loading configuration file: <_io.BufferedReader name='mkdocs-ci.yml'>
DEBUG   -  Loaded theme configuration for 'material' from '/usr/local/lib/python3.10/site-packages/material/templates/mkdocs_theme.yml': {'language': 'en', 'direction': None, 'features': [], 'font': {'text': 'Roboto', 'code': 'Roboto Mono'}, 'icon': None, 'favicon': 'assets/images/favicon.png', 'static_templates': ['404.html']}
INFO    -  DeprecationWarning: pkg_resources is deprecated as an API. See https://setuptools.pypa.io/en/latest/pkg_resources.html
  File "/usr/local/lib/python3.10/site-packages/pybtex/plugin/__init__.py", line 26, in <module>
    import pkg_resources
  File "/usr/local/lib/python3.10/site-packages/pkg_resources/__init__.py", line 102, in <module>
    warnings.warn(
INFO    -  DeprecationWarning: warning_filter doesn't do anything since MkDocs 1.2 and will be removed soon. All messages on the `mkdocs` logger get counted automatically.
  File "/usr/local/lib/python3.10/site-packages/mkdocs_bibtex/utils.py", line 10, in <module>
    from mkdocs.utils import warning_filter
  File "/usr/local/lib/python3.10/site-packages/mkdocs/utils/__init__.py", line 453, in __getattr__
    warnings.warn(
WARNING -  Config value 'plugins': Plugin 'bibtex' option 'cite_style': Unrecognised configuration name: cite_style
DEBUG   -  Config value 'config_file_path' = 'mkdocs-ci.yml'
DEBUG   -  Config value 'site_name' = "Les cahiers d'IDEES"
DEBUG   -  Config value 'nav' = None
DEBUG   -  Config value 'pages' = None
DEBUG   -  Config value 'exclude_docs' = None
DEBUG   -  Config value 'not_in_nav' = None
DEBUG   -  Config value 'site_url' = None
DEBUG   -  Config value 'site_description' = None
DEBUG   -  Config value 'site_author' = None
DEBUG   -  Config value 'theme' = Theme(name='material', dirs=['/usr/local/lib/python3.10/site-packages/material/templates', '/usr/local/lib/python3.10/site-packages/mkdocs/templates'], static_templates={'sitemap.xml', '404.html'}, name='material', locale=Locale('en'), language='fr', direction=None, features=[], font={'text': 'Roboto', 'code': 'Roboto Mono'}, icon=None, favicon='assets/images/favicon.png', logo='assets/logo.png', palette={'primary': 'white', 'accent': 'blue'})
DEBUG   -  Config value 'docs_dir' = '/builds/umr-idees/formations-cahier-idees/cahier-idees-metasite/docs'
DEBUG   -  Config value 'site_dir' = '/builds/umr-idees/formations-cahier-idees/cahier-idees-metasite/site'
DEBUG   -  Config value 'copyright' = None
DEBUG   -  Config value 'google_analytics' = None
DEBUG   -  Config value 'dev_addr' = _IpAddressValue(host='127.0.0.1', port=8000)
DEBUG   -  Config value 'use_directory_urls' = True
DEBUG   -  Config value 'repo_url' = None
DEBUG   -  Config value 'repo_name' = None
DEBUG   -  Config value 'edit_uri_template' = None
DEBUG   -  Config value 'edit_uri' = None
DEBUG   -  Config value 'extra_css' = []
DEBUG   -  Config value 'extra_javascript' = []
DEBUG   -  Config value 'extra_templates' = []
DEBUG   -  Config value 'markdown_extensions' = ['toc', 'tables', 'fenced_code', 'footnotes']
DEBUG   -  Config value 'mdx_configs' = {}
DEBUG   -  Config value 'strict' = False
DEBUG   -  Config value 'remote_branch' = 'gh-pages'
DEBUG   -  Config value 'remote_name' = 'origin'
DEBUG   -  Config value 'extra' = {}
DEBUG   -  Config value 'plugins' = {'material/blog': <material.plugins.blog.plugin.BlogPlugin object at 0x7f9a3600df30>, 'material/tags': <material.plugins.tags.plugin.TagsPlugin object at 0x7f9a36040370>, 'material/meta': <material.plugins.meta.plugin.MetaPlugin object at 0x7f9a36041ba0>, 'git-revision-date-localized': <mkdocs_git_revision_date_localized_plugin.plugin.GitRevisionDateLocalizedPlugin object at 0x7f9a36042380>, 'material/search': <material.plugins.search.plugin.SearchPlugin object at 0x7f9a35ce4a00>, 'bibtex': <mkdocs_bibtex.plugin.BibTexPlugin object at 0x7f9a35b48580>}
DEBUG   -  Config value 'hooks' = {}
DEBUG   -  Config value 'watch' = []
DEBUG   -  Config value 'validation' = {'nav': {'omitted_files': 20, 'not_found': 30, 'absolute_links': 20}, 'links': {'not_found': 30, 'absolute_links': 20, 'unrecognized_links': 20}}
DEBUG   -  Running 2 `startup` events
DEBUG   -  Running 5 `config` events
WARNING:root:
                [git-revision-date-localized-plugin] Running on a GitLab runner might lead to wrong
                Git revision dates due to a shallow git fetch depth.
                Make sure to set GIT_DEPTH to 0 in your .gitlab-ci.yml file
                (see https://docs.gitlab.com/ee/user/project/pipelines/settings.html#git-shallow-clone).
                
DEBUG   -  Looking for translations for locale 'en'
DEBUG   -  No translations found here: '/usr/local/lib/python3.10/site-packages/mkdocs/templates/locales'
DEBUG   -  No translations found here: '/usr/local/lib/python3.10/site-packages/material/templates/locales'
DEBUG   -  Looking for translations for locale 'en'
DEBUG   -  No translations found here: '/usr/local/lib/python3.10/site-packages/mkdocs/templates/locales'
DEBUG   -  No translations found here: '/usr/local/lib/python3.10/site-packages/material/templates/locales'
DEBUG   -  Looking for translations for locale 'en'
DEBUG   -  No translations found here: '/usr/local/lib/python3.10/site-packages/mkdocs/templates/locales'
DEBUG   -  No translations found here: '/usr/local/lib/python3.10/site-packages/material/templates/locales'
DEBUG   -  Parsing bibtex file 'docs/bib/notebooks.bib'...
INFO    -  SUCCESS Parsing bibtex file 'docs/bib/notebooks.bib'
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: /builds/umr-idees/formations-cahier-idees/cahier-idees-metasite/site
DEBUG   -  Looking for translations for locale 'en'
DEBUG   -  No translations found here: '/usr/local/lib/python3.10/site-packages/mkdocs/templates/locales'
DEBUG   -  No translations found here: '/usr/local/lib/python3.10/site-packages/material/templates/locales'
DEBUG   -  Running 2 `files` events
DEBUG   -  Running 2 `nav` events
DEBUG   -  Looking for translations for locale 'en'
DEBUG   -  No translations found here: '/usr/local/lib/python3.10/site-packages/mkdocs/templates/locales'
DEBUG   -  No translations found here: '/usr/local/lib/python3.10/site-packages/material/templates/locales'
DEBUG   -  Looking for translations for locale 'en'
DEBUG   -  No translations found here: '/usr/local/lib/python3.10/site-packages/mkdocs/templates/locales'
DEBUG   -  No translations found here: '/usr/local/lib/python3.10/site-packages/material/templates/locales'
DEBUG   -  Reading markdown pages.
DEBUG   -  Reading: index.md
DEBUG   -  Running 5 `page_markdown` events
DEBUG   -  Formatting all bib entries...
INFO    -  SUCCESS Formatting all bib entries
DEBUG   -  Replacing citation keys with the generated ones...
DEBUG   -  SUCCESS Replacing citation keys with the generated ones
DEBUG   -  Running 1 `page_content` events
DEBUG   -  Reading: blog/index.md
DEBUG   -  Running 5 `page_markdown` events
WARNING:root:
                [git-revision-date-localized-plugin] Running on a GitLab runner might lead to wrong
                Git revision dates due to a shallow git fetch depth.
                Make sure to set GIT_DEPTH to 0 in your .gitlab-ci.yml file
                (see https://docs.gitlab.com/ee/user/project/pipelines/settings.html#git-shallow-clone).
                
DEBUG   -  Formatting all bib entries...
INFO    -  SUCCESS Formatting all bib entries
DEBUG   -  Replacing citation keys with the generated ones...
DEBUG   -  SUCCESS Replacing citation keys with the generated ones
DEBUG   -  Running 1 `page_content` events
DEBUG   -  Reading: formations/enquete-et-entretiens.md
DEBUG   -  Running 5 `page_markdown` events
WARNING:root:
                [git-revision-date-localized-plugin] Running on a GitLab runner might lead to wrong
                Git revision dates due to a shallow git fetch depth.
                Make sure to set GIT_DEPTH to 0 in your .gitlab-ci.yml file
                (see https://docs.gitlab.com/ee/user/project/pipelines/settings.html#git-shallow-clone).
                
DEBUG   -  Formatting all bib entries...
INFO    -  SUCCESS Formatting all bib entries
DEBUG   -  Replacing citation keys with the generated ones...
DEBUG   -  SUCCESS Replacing citation keys with the generated ones
DEBUG   -  Running 1 `page_content` events
DEBUG   -  Reading: formations/r-initiations.md
DEBUG   -  Running 5 `page_markdown` events
DEBUG   -  Formatting all bib entries...
INFO    -  SUCCESS Formatting all bib entries
DEBUG   -  Replacing citation keys with the generated ones...
DEBUG   -  SUCCESS Replacing citation keys with the generated ones
DEBUG   -  Running 1 `page_content` events
DEBUG   -  Reading: formations/r-textometrie.md
DEBUG   -  Running 5 `page_markdown` events
DEBUG   -  Formatting all bib entries...
DEBUG   -  Converting bibtex entry 'Toureille2024' without pandoc
DEBUG   -  SUCCESS Converting bibtex entry 'Toureille2024' without pandoc
INFO    -  SUCCESS Formatting all bib entries
DEBUG   -  Replacing citation keys with the generated ones...
DEBUG   -  SUCCESS Replacing citation keys with the generated ones
ERROR   -  Error reading page 'formations/r-textometrie.md': bad escape \u at position 156
DEBUG   -  Running 1 `shutdown` events
Traceback (most recent call last):
  File "/usr/local/lib/python3.10/sre_parse.py", line 1051, in parse_template
    this = chr(ESCAPES[this][1])
KeyError: '\\u'
During handling of the above exception, another exception occurred:
Traceback (most recent call last):
  File "/usr/local/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
  File "/usr/local/lib/python3.10/site-packages/click/core.py", line 1157, in __call__
    return self.main(*args, **kwargs)
  File "/usr/local/lib/python3.10/site-packages/click/core.py", line 1078, in main
    rv = self.invoke(ctx)
  File "/usr/local/lib/python3.10/site-packages/click/core.py", line 1688, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/usr/local/lib/python3.10/site-packages/click/core.py", line 1434, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/usr/local/lib/python3.10/site-packages/click/core.py", line 783, in invoke
    return __callback(*args, **kwargs)
  File "/usr/local/lib/python3.10/site-packages/mkdocs/__main__.py", line 286, in build_command
    build.build(cfg, dirty=not clean)
  File "/usr/local/lib/python3.10/site-packages/mkdocs/commands/build.py", line 322, in build
    _populate_page(file.page, config, files, dirty)
  File "/usr/local/lib/python3.10/site-packages/mkdocs/commands/build.py", line 171, in _populate_page
    page.markdown = config.plugins.on_page_markdown(
  File "/usr/local/lib/python3.10/site-packages/mkdocs/plugins.py", line 575, in on_page_markdown
    return self.run_event('page_markdown', markdown, page=page, config=config, files=files)
  File "/usr/local/lib/python3.10/site-packages/mkdocs/plugins.py", line 507, in run_event
    result = method(item, **kwargs)
  File "/usr/local/lib/python3.10/site-packages/mkdocs_bibtex/plugin.py", line 145, in on_page_markdown
    markdown = re.sub(
  File "/usr/local/lib/python3.10/re.py", line 209, in sub
    return _compile(pattern, flags).sub(repl, string, count)
  File "/usr/local/lib/python3.10/re.py", line 326, in _subx
    template = _compile_repl(template, pattern)
  File "/usr/local/lib/python3.10/re.py", line 317, in _compile_repl
    return sre_parse.parse_template(repl, pattern)
  File "/usr/local/lib/python3.10/sre_parse.py", line 1054, in parse_template
    raise s.error('bad escape %s' % this, len(this))
re.error: bad escape \u at position 156

The file formations/r-textometrie.md :

---
title: La Statistique Textuelle avec R
icon:
---

# La « Statistique Textuelle » avec R 

Ce jour et demi de formation aura pour objectif de reprendre les fondamentaux de de la statistique textuelle (Lebart et Salem, 1994) à travers leur implémentation dans R via le package quanteda (Watanabe et Müller, 2023).

Nous avons fait le choix d'un format mixte :

- 1 journée de Formation et 
- 1/2 journée d'Atelier afin que les participants puissent venir tester les méthodes avec leur propre corpus.

Cette formation s’adresse à toute personne confrontée par la manipulation de données textuelles (données d’enquête, archives, chaînes de caractères scrapées, etc.) intéressée par une analyse quantitative exploratoire du contenu. L’avantage d’une implémentation dans R, réside dans la possibilité de reproduire des analyses disponibles dans des logiciels historiques de la statistique textuelle souvent payants (Alceste, module d’analyse lexical de SPAD) ou dans les possibilités de répétabilité, d’automatisation d’opérations existantes dans d’autres logiciels d’analyse textuelle (cas de TXM).

Pour une application en sciences sociales le contenu des textes sera analysé relativement à leur contexte de production (différences lexicales entre sources, auteurs, périodes, par exemple).

Des rappels théoriques et des applications sur des corpus d’exemple seront proposées sur les méthodes suivantes :

- La transformation de textes (chaînes de caractères) en tableau (tableau lexical entier : TLE),
- Donc la modélisation du tableau de données (définition des unités de contexte et des unités lexicales, sélection des termes et autres formes de « nettoyage » des données textuelles),
- L’analyse du lexique et du concordancier,
- L’analyse du vocabulaire spécifique entre des sous-corpus (construction de tableaux lexicaux agrégés – TLA et test du chi2),
- L’analyse des correspondances (AFC) appliquée à un TLA,
- L’analyse des cooccurrences et des segments répétés,
- Selon le temps disponible : méthodes de classification de texte (CAH et/ou CDH de Reinert – méthode historiquement utilisée dans Alceste et Iramutec – via le package rainette – Barnier, 2023).

# Historique des formations

- 5 et 6 février 2024 au Havre (initiation), [Etienne Toureille](https://umr-idees.fr/laboratoire/annuaire/etienne-toureille), créateur de la formation initiale

# Citation

[@Toureille2024]

With :

mkdocs_bibtex-2.14.1
python3.10

Error occurs when "journal" is empty

Hi!

When citing preprints such that the bibtex field "journal" is empty, I got errors like

Error reading page 'xx': missing journal in xx
Traceback (most recent call last):
  File "/opt/homebrew/lib/python3.9/site-packages/pybtex/database/__init__.py", line 503, in _find_field
    return self.fields[name]
  File "/opt/homebrew/lib/python3.9/site-packages/pybtex/utils.py", line 163, in __getitem__
    return self._dict[key.lower()]
KeyError: 'journal'

During handling of the above exception, another exception occurred:
......

Is there a way to escape empty fields? Thx!

Your .dependabot/config.yml contained invalid details

Dependabot encountered the following error when parsing your .dependabot/config.yml:

Automerging is not enabled for this account. You can enable it from the [account settings](https://app.dependabot.com/accounts/shyamd/settings) screen in your Dependabot dashboard.

Please update the config file to conform with Dependabot's specification using our docs and online validator.

Use Bibentry instead of cite

Just learned that \bibentry gets bibtex to print out the whole citation in-line so this could be used to get the key: citation relationship from pandoc.

Pandoc style misses support for multiple keys

Pandoc generates citations with multiple keys. For example,

[@JMLReferenceManual11; @Leavens-Baker-Ruby04]

This plugin is not able to handle these citations. The regex (and the succeeding code) is streamlined for the single-key usage case.

Feature: adding a recursive option to fetch `.bib` files ?

Hi !

First of all thanks for this great repo !
I forked it since in my project, I use multiple .bib files scattered across the docs folder. As such, I added a recursive option with a simple change when fetching the .bib files :

if self.config["recursive"]:
    bibfiles.extend(Path(self.config["bib_dir"]).rglob("*.bib"))
else:
    bibfiles.extend(Path(self.config["bib_dir"]).glob("*.bib"))

Would you be interested in a PR for this ?

Add an option for loading an api key

The flexibility of a URL is great, but they'd prefer API keys were in the header: https://www.zotero.org/support/dev/web_api/v3/basics

Any chance an option following their API and mkdocs environmental variable options could be added, something like:

- bibtex:
    bib_file:
      zenodo: true
      zenodo_user_or_goup_id: !ENV [A_SYSTEM_VAR, ZENODO_GROUP, "1234567"]  # Zenodo group ID number
      zenodo_api_key: !ENV [ANOTHER_SYSTEM_VAR, A_GITHUB_ENV, ZENODO_API_KEY]

to fill in this sort of template:

https://api.zotero.org/groups/${zenodo_user_or_group_id}/items?format=bibtex&key=${zenodo_api_key}

A slicker option could use pyyaml-env or python-dotenv to use a local .env like:

ZENODO_GROUP=1234567
ZENODO_API_KEY=12345671234567

but that might be a feature request for mkdocs generally. That was mentioned in this ticket but as best I understand only environmental variables were added via pyyaml-env-tag (hence the documentation linked above which follows the same format).

options csl_file and cite_style don't seem to be effective

I just realized that the options csl_file and cite_style don't seem to be functioning as expected. Should the config.get() actually be self.config.get() in the following lines? I changed the code this way and then the 2 options appear to be working again.

mkdocs-bibtex/mkdocs_bibtex/plugin.py

Line 73 in a7d0a3c

cite_style = config.get("cite_style", "pandoc")

mkdocs-bibtex/mkdocs_bibtex/plugin.py

Line 84 in a7d0a3c

self.csl_file = config.get("csl_file", None)

Does not parse citations in docstrings using mkdocstrings

Hi,

While this plugin works great with normal markdown documents, most of my model documentation is located in the docstrings of functions. Unfortunately, the citations I put in the docstrings (and which are pulled in the markdown using mkdocstrings) are not parsed:

Say we have a file testfile.py:

def testfunction(x):
    """Test docstring with [@citekey1] citation"""
    return x * 2

and the docstring is used in a markdown file using:

# Markdown file with extra docs

:::testfile.testfunction

This would return:

Test docstring with [@citekey1] citation

Crash with .csl

Happy to see that Pandoc versioning was implemented with v1.0.0, nice work!

It seems to have introduced a bug regarding the csl_file input. Mine is crashing upon mkdocs serve when a .cslfile is included, but runs smoothly when it's not.

The relevant error lines look like this:

File "/usr/local/lib/python3.9/site-packages/mkdocs_bibtex/plugin.py", line 109, in on_page_markdown
    references = self.format_citations(citations)
  File "/usr/local/lib/python3.9/site-packages/mkdocs_bibtex/plugin.py", line 151, in format_citations
    entry_text = to_markdown_pandoc(entry, self.csl_file)
  File "/usr/local/lib/python3.9/site-packages/mkdocs_bibtex/plugin.py", line 201, in to_markdown_pandoc
    citation = citation_regex.findall(" ".join(markdown.split("\n")))[0]
IndexError: list index out of range

Citing @software entry with mkdocs ?

Hi,

Thanks for your work,

There are new csl extension style for bibtex/biblatex that are added to manage the @software entry :

I try to use @software with mkdocs-bibtex without success, and this is probably normal because that need some works to integrate i suppose.

Mkdocs material is really used for dev doc, so citing software with the good biblatex entry could be cool :)

Best,
SR

Multiple bib files?

The test-files suggest that multiple bib files can be used with this plugin. I was trying to use multiple bib files by specifying the bib files as a list in the YAML file. But that doesn't seem to work.

If it is possible to use multiple bib files, it would be helpful to know how I should define it in the YAML file. Thank you!

Possibility to add render all references in bib file in first page

Hi! The plugin works very well for showing citations in each page. Thank you very much!

I would really like to be able to put in my index.md file the full bibliography used for the entire webpage. It seems the \full_bibliography or \bibliography commands do not work at all. Is there a way to accomplish this?

Best regards,

Alex.

Several issues with Citavi

Hi there,

I noticed two things that might not require fixing, but I'd at least want to point out to the next person trying to get this plugin work with Citavi: The regex currently does not capture bibtex keys that contain a period, e. g. @Bermudez.2020. This is the default setting for Citavi, and it took me quite a while to figure out why the plugin wasn't parsing my citations in mkdocs.

Also, enabling the URL-package in Citavi (i. e. rendering the URLs in the bibtex file as url = {\url{https://doi.org/10.21577/0103-5053.20190253}}) causes the following error:


ERROR    -  Error reading page 'sandalwood.md': bad escape \u at position 248
Traceback (most recent call last):
  File "/usr/lib/python3.9/sre_parse.py", line 1039, in parse_template
    this = chr(ESCAPES[this][1])
KeyError: '\\u'

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "/usr/local/bin/mkdocs", line 8, in <module>
    sys.exit(cli())
  File "/usr/local/lib/python3.9/dist-packages/click/core.py", line 1130, in __call__
    return self.main(*args, **kwargs)
  File "/usr/local/lib/python3.9/dist-packages/click/core.py", line 1055, in main
    rv = self.invoke(ctx)
  File "/usr/local/lib/python3.9/dist-packages/click/core.py", line 1657, in invoke
    return _process_result(sub_ctx.command.invoke(sub_ctx))
  File "/usr/local/lib/python3.9/dist-packages/click/core.py", line 1404, in invoke
    return ctx.invoke(self.callback, **ctx.params)
  File "/usr/local/lib/python3.9/dist-packages/click/core.py", line 760, in invoke
    return __callback(*args, **kwargs)
  File "/usr/local/lib/python3.9/dist-packages/mkdocs/__main__.py", line 250, in build_command
    build.build(cfg, dirty=not clean)
  File "/usr/local/lib/python3.9/dist-packages/mkdocs/commands/build.py", line 308, in build
    _populate_page(file.page, config, files, dirty)
  File "/usr/local/lib/python3.9/dist-packages/mkdocs/commands/build.py", line 177, in _populate_page
    page.markdown = config.plugins.run_event(
  File "/usr/local/lib/python3.9/dist-packages/mkdocs/plugins.py", line 520, in run_event
    result = method(item, **kwargs)
  File "/usr/local/lib/python3.9/dist-packages/mkdocs_bibtex/plugin.py", line 132, in on_page_markdown
    markdown = re.sub(
  File "/usr/lib/python3.9/re.py", line 210, in sub
    return _compile(pattern, flags).sub(repl, string, count)
  File "/usr/lib/python3.9/re.py", line 327, in _subx
    template = _compile_repl(template, pattern)
  File "/usr/lib/python3.9/re.py", line 318, in _compile_repl
    return sre_parse.parse_template(repl, pattern)
  File "/usr/lib/python3.9/sre_parse.py", line 1042, in parse_template
    raise s.error('bad escape %s' % this, len(this))
re.error: bad escape \u at position 248

No longer supports bibtex keys with ":"

Hi,

since version 2.0.0 citations with colons in the bibtex key are no longer parsed/recognized. Version 1.2.0 was the last version where this worked.

[@author:1234] works in 1.2.0 but not in 2.0.0 and newer.

Thanks,
Tobias

Thank you!
Jobin

Missing dependency `pkg_resources`

The library depends on pkg_resources but it is not listed in requirements.txt so after pip install mkdocs-bibtex I'm getting

import mkdocs_bibtex

File ~/Library/Caches/pypoetry/virtualenvs/mfglib-SRAM7qJs-py3.9/lib/python3.9/site-packages/mkdocs_bibtex/__init__.py:1
----> 1 from pkg_resources import DistributionNotFound, get_distribution
      3 from mkdocs_bibtex.plugin import BibTexPlugin
      5 try:

ModuleNotFoundError: No module named 'pkg_resources'