Refactor for easier updating

.github/workflows/testing.yml

@@ -39,7 +39,7 @@ jobs:
       matrix:
         os: [ubuntu-latest]
         python-version: [3.9, '3.10', 3.11, 3.12]
-        pandoc-version: [2.9.2, 2.14.0.3]
+        pandoc-version: [2.14.0.3, 3.6.2]
     runs-on: ${{ matrix.os }}
 
     steps:

.gitignore

@@ -102,3 +102,6 @@ venv.bak/
 
 # mypy
 .mypy_cache/
+
+# example
+example/site

.pre-commit-config.yaml

@@ -1,15 +1,15 @@
 repos:
-    - repo: https://github.com/pre-commit/pre-commit-hooks
-      rev: v4.4.0
-      hooks:
-      -   id: check-yaml
-      -   id: end-of-file-fixer
-      -   id: trailing-whitespace
-    - repo: https://github.com/ambv/black
-      rev: 22.12.0
-      hooks:
-      - id: black
-    - repo: https://github.com/charliermarsh/ruff-pre-commit
-      rev: 'v0.0.207'
-      hooks:
-        - id: ruff
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.4.0
+    hooks:
+    -   id: check-yaml
+    -   id: end-of-file-fixer
+    -   id: trailing-whitespace
+  - repo: https://github.com/charliermarsh/ruff-pre-commit
+    rev: 'v0.9.2'
+    hooks:
+      # Run the linter.
+      - id: ruff
+        args: [ --fix ]
+      # Run the formatter.
+      - id: ruff-format

README.md

@@ -40,44 +40,90 @@ The footnotes extension is how citations are linked for now.
 - `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]`
+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.
+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   -  Parsing bibtex file 'docs/bib/papers.bib'...
-INFO    -  SUCCESS Parsing bibtex file 'docs/bib/papers.bib'
-DEBUG   -  Downloading CSL file from URL https://raw.githubusercontent.com/citation-style-language/styles/master/apa-6th-edition.csl to temporary file...
-INFO    -  CSL file downladed from URL https://raw.githubusercontent.com/citation-style-language/styles/master/apa-6th-edition.csl to temporary file (<tempfile._TemporaryFileWrapper object at 0x00000203E4F2F650>)
+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
 (...)
-DEBUG   -  Reading: publications.md
-DEBUG   -  Running 2 `page_markdown` events
-DEBUG   -  Formatting all bib entries...
-DEBUG   -  --Converting bibtex entry 'foo2019' with CSL file 'docs/bib/apa_verbose.csl' using pandoc>=2.11
-DEBUG   -  --SUCCESS Converting bibtex entry 'foo2019' with CSL file 'docs/bib/apa_verbose.csl' using pandoc>=2.11
-DEBUG   -  --Converting bibtex entry 'bar2024' with CSL file 'docs/bib/apa_verbose.csl' using pandoc>=2.11
-DEBUG   -  --SUCCESS Converting bibtex entry 'bar2024' with CSL file 'docs/bib/apa_verbose.csl' using pandoc>=2.11
-INFO    -  SUCCESS Formatting all bib entries
-DEBUG   -  Replacing citation keys with the generated ones...
-DEBUG   -  --Rendering citation inline for '[@foo2019]'...
-DEBUG   -  ----Converting pandoc citation key '[@foo2019]' with CSL file 'docs/bib/apa_verbose.csl' and Bibliography file '(...)/tmpzt7t8p0y/temp.bib'...
-DEBUG   -  ----SUCCESS Converting pandoc citation key '[@foo2019]' with CSL file 'docs/bib/apa_verbose.csl' and Bibliography file '(...)/tmpzt7t8p0y/temp.bib'
-DEBUG   -  --SUCCESS Rendering citation inline for '[@foo2019]'
-DEBUG   -  --Rendering citation inline for '[@bar2024]'...
-DEBUG   -  ----Converting pandoc citation key '[@bar2024]' with CSL file 'docs/bib/apa_verbose.csl' and Bibliography file '(...)/tmpzt7t8p0y/temp.bib'...
-DEBUG   -  ----SUCCESS Converting pandoc citation key '[@bar2024]' with CSL file 'docs/bib/apa_verbose.csl' and Bibliography file '(...)/tmpzt7t8p0y/temp.bib'
-DEBUG   -  --SUCCESS Rendering citation inline for '[@bar2024]'
-DEBUG   -  SUCCESS Replacing citation keys with the generated ones
 ```

example/docs/full_bib.md

@@ -0,0 +1,3 @@
+# This is a full bibliography
+
+\full_bibliography

example/docs/index.md

@@ -0,0 +1,24 @@
+# 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 [@nonexistent]
+
+## Citation with affix
+
+Citation [@test, see pp. 100]
+
+## Citation with multiple affixes
+
+Citation [see @test, pp. 100, 200]
+
+
+## Bibliography
+
+\bibliography

example/mkdocs.yml

@@ -0,0 +1,15 @@
+site_name: Example Mkdocs-bibtex
+
+plugins:
+  - bibtex:
+      bib_file: refs.bib
+      csl_file: nature.csl
+      #csl_file: springer-basic-author-date.csl
+
+markdown_extensions:
+  - footnotes
+  - pymdownx.caret
+
+nav:
+  - Index: index.md
+  - Bibliography: full_bib.md

example/nature.csl

@@ -0,0 +1,132 @@
+<?xml version="1.0" encoding="utf-8"?>
+<style xmlns="http://purl.org/net/xbiblio/csl" class="in-text" version="1.0" demote-non-dropping-particle="sort-only" default-locale="en-GB">
+  <info>
+    <title>Nature</title>
+    <id>http://www.zotero.org/styles/nature</id>
+    <link href="http://www.zotero.org/styles/nature" rel="self"/>
+    <link href="http://www.nature.com/nature/authors/gta/index.html#a5.4" rel="documentation"/>
+    <link href="http://www.nature.com/srep/publish/guidelines#references" rel="documentation"/>
+    <author>
+      <name>Michael Berkowitz</name>
+      <email>mberkowi@gmu.edu</email>
+    </author>
+    <category citation-format="numeric"/>
+    <category field="science"/>
+    <category field="generic-base"/>
+    <issn>0028-0836</issn>
+    <eissn>1476-4687</eissn>
+    <updated>2019-10-08T13:18:12+00:00</updated>
+    <rights license="http://creativecommons.org/licenses/by-sa/3.0/">This work is licensed under a Creative Commons Attribution-ShareAlike 3.0 License</rights>
+  </info>
+  <macro name="title">
+    <choose>
+      <if type="bill book graphic legal_case legislation motion_picture report song" match="any">
+        <text variable="title" font-style="italic"/>
+      </if>
+      <else>
+        <text variable="title"/>
+      </else>
+    </choose>
+  </macro>
+  <macro name="author">
+    <names variable="author">
+      <name sort-separator=", " delimiter=", " and="symbol" initialize-with=". " delimiter-precedes-last="never" name-as-sort-order="all"/>
+      <label form="short" prefix=", "/>
+      <et-al font-style="italic"/>
+    </names>
+  </macro>
+  <macro name="access">
+    <choose>
+      <if variable="volume"/>
+      <else-if variable="DOI">
+        <text variable="DOI" prefix="doi:"/>
+      </else-if>
+    </choose>
+  </macro>
+  <macro name="issuance">
+    <choose>
+      <if type="bill book graphic legal_case legislation motion_picture song thesis chapter paper-conference" match="any">
+        <group delimiter="; " suffix=".">
+          <group delimiter=", " prefix="(" suffix=")">
+            <text variable="publisher" form="long"/>
+            <date variable="issued">
+              <date-part name="year"/>
+            </date>
+          </group>
+        </group>
+      </if>
+      <else-if type="report webpage post post-weblog" match="any">
+        <group delimiter=" ">
+          <text variable="URL"/>
+          <date date-parts="year" form="text" variable="issued" prefix="(" suffix=")"/>
+        </group>
+      </else-if>
+      <else>
+        <date variable="issued" prefix="(" suffix=")">
+          <date-part name="year"/>
+        </date>
+      </else>
+    </choose>
+  </macro>
+  <macro name="container-title">
+    <choose>
+      <if type="article-journal">
+        <text variable="container-title" font-style="italic" form="short"/>
+      </if>
+      <else>
+        <text variable="container-title" font-style="italic"/>
+      </else>
+    </choose>
+  </macro>
+  <macro name="editor">
+    <choose>
+      <if type="chapter paper-conference" match="any">
+        <names variable="editor" prefix="(" suffix=")">
+          <label form="short" suffix=" "/>
+          <name and="symbol" delimiter-precedes-last="never" initialize-with=". " name-as-sort-order="all"/>
+        </names>
+      </if>
+    </choose>
+  </macro>
+  <macro name="volume">
+    <choose>
+      <if type="article-journal" match="any">
+        <text variable="volume" font-weight="bold" suffix=","/>
+      </if>
+      <else>
+        <group delimiter=" ">
+          <label variable="volume" form="short"/>
+          <text variable="volume"/>
+        </group>
+      </else>
+    </choose>
+  </macro>
+  <citation collapse="citation-number">
+    <sort>
+      <key variable="citation-number"/>
+    </sort>
+    <layout vertical-align="sup" delimiter=",">
+      <text variable="citation-number"/>
+    </layout>
+  </citation>
+  <bibliography et-al-min="6" et-al-use-first="1" second-field-align="flush" entry-spacing="0" line-spacing="2">
+    <layout suffix=".">
+      <text variable="citation-number" suffix="."/>
+      <group delimiter=" ">
+        <text macro="author" suffix="."/>
+        <text macro="title" suffix="."/>
+        <choose>
+          <if type="chapter paper-conference" match="any">
+            <text term="in"/>
+          </if>
+        </choose>
+        <text macro="container-title"/>
+        <text macro="editor"/>
+        <text macro="volume"/>
+        <text variable="page"/>
+        <text macro="issuance"/>
+        <text macro="access"/>
+      </group>
+    </layout>
+  </bibliography>
+</style>

example/refs.bib

@@ -0,0 +1,41 @@
+@article{test,
+  title={Test Title},
+  author={Author, First and Author, Second},
+  journal={Testing Journal},
+  volume={1},
+  year={2019},
+  publisher={Test_Publisher}
+}
+
+@article{test2,
+  title={{Test Title (TT)}},
+  author={Author, First and Author, Second},
+  journal={Testing Journal (TJ)},
+  volume={1},
+  year={2019},
+  publisher={Test_Publisher (TP)}
+}
+
+@article{Bivort2016,
+  title = {Evidence for Selective Attention in the Insect Brain},
+  author = {De Bivort, Benjamin L. and Van Swinderen, Bruno},
+  year = {2016},
+  volume = {15},
+  pages = {1--7},
+  issn = {22145753},
+  doi = {10.1016/j.cois.2016.02.007},
+  abstract = {The capacity for selective attention appears to be required by any animal responding to an environment containing multiple objects, although this has been difficult to study in smaller animals such as insects. Clear operational characteristics of attention however make study of this crucial brain function accessible to any animal model. Whereas earlier approaches have relied on freely behaving paradigms placed in an ecologically relevant context, recent tethered preparations have focused on brain imaging and electrophysiology in virtual reality environments. Insight into brain activity during attention-like behavior has revealed key elements of attention in the insect brain. Surprisingly, a variety of brain structures appear to be involved, suggesting that even in the smallest brains attention might involve widespread coordination of neural activity.},
+  journal = {Current Opinion in Insect Science},
+  keywords = {attention,bees,drosophila,insects},
+  pmid = {27436727}
+}
+
+@article{test_citavi,
+  title={{Test Title (TT)}},
+  author={Author, First and Author, Second},
+  journal={Testing Journal (TJ)},
+  volume={1},
+  year={2019},
+  publisher={Test_Publisher (TP)},
+  url = {\url{https://doi.org/10.21577/0103-5053.20190253}}
+}