Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[feat]: Support for global bibliographies #270

Draft
wants to merge 4 commits into
base: main
Choose a base branch
from

Conversation

thdhondt
Copy link
Contributor

Hello @shyamd!

One feature that would be very useful for my work would be a global and latex-like bibliography. While thinking about this feature, I noted the following:

  • The content of the global bibliography should be independent of where the \full_bibliography tag is located in the documentation.
  • Footnotes are well suited for local bibliography, but not for a global one as they can't really refer to another page.
  • The indices used to refer to a bibliography entry should be unique across the whole documentation for a global bibliography

I gave this project a try and ended up doing a pretty extensive rewrite of the plugin ...
I tried to fix the first issue by pre-parsing the files of the documentation in the on_file mkdocs callback.
The second issue is handled by introducing different citation formats (footnote, inline, link).
The last issue is fixed by having global or per-page bibliography indexes depending on the setting chosen by the user.

I have also changed some of the configuration options of the plugin.
The default behavior results in the same output as today:

plugins:
  - bibtex:
      bib_file: "refs.bib"
      cite_format: "footnote"
      bib_type: "per_page"

A global bibliography would be configured this way:

plugins:
  - bibtex:
      bib_file: "refs.bib"
      cite_format: "link"
      bib_type: "global"
      global_bib_ref: "\bibliography.md"

Even though there are quite a lot of changes that should still be made before this can be merged, it is in a mostly functional state. I was curious if you would be interested in taking over some of these changes in the official plugin.

I have not yet updated any of the tests, documentation, etc.

@thdhondt thdhondt marked this pull request as draft September 27, 2024 12:59
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant