feat: add global bibliography support to pandoc-reader plugin

Filip · Filip · commit 99da1e21daf0 · 2025-07-08T20:47:27.000+02:00
- Add support for global bibliography files with configurable names
- Maintain backward compatibility with individual bibliography files
- Add PANDOC_GLOBAL_BIB_FILES setting
- Add comprehensive tests for all scenarios
- Update documentation and provide example configuration
diff --git a/README.md b/README.md
@@ -181,9 +181,31 @@ Without these settings, citations will not be processed by the plugin.
 
 It is not necessary to specify the `+citations` extension since it is enabled by default. However, if you were to disable citations by specifying `-citations` in `PANDOC_EXTENSIONS` or by setting `reader: markdown-citations` in your defaults file, citations will **not** work.
 
-You may write your bibliography in any format supported by Pandoc with the appropriate extensions specified. However, you **must** name the bibliography file the same as your post.
+You may write your bibliography in any format supported by Pandoc with the appropriate extensions specified. The plugin supports both individual and global bibliography files.
 
-For example, a post with the file name `my-post.md` should have a bibliography file called `my-post.bib`, `my-post.json`, `my-post.yaml` or `my-post.bibtex` in the same directory as your post, or in a subdirectory of the directory that your blog resides in. Failure to do so will prevent the references from being picked up.
+#### Individual Bibliography Files
+
+By default, the plugin looks for bibliography files that have the same name as your post. For example, a post with the file name `my-post.md` should have a bibliography file called `my-post.bib`, `my-post.json`, `my-post.yaml` or `my-post.bibtex` in the same directory as your post, or in a subdirectory of the directory that your blog resides in.
+
+#### Global Bibliography Files
+
+You can also use global bibliography files that contain references for multiple articles. The plugin will automatically search for global bibliography files with the following default names:
+
+* `_bibliography.bib`, `_bibliography.json`, `_bibliography.yaml`, `_bibliography.bibtex`
+* `bibliography.bib`, `bibliography.json`, `bibliography.yaml`, `bibliography.bibtex`
+* `references.bib`, `references.json`, `references.yaml`, `references.bibtex`
+
+To customize the global bibliography file names, set the `PANDOC_GLOBAL_BIB_FILES` setting in your Pelican settings file:
+
+```python
+PANDOC_GLOBAL_BIB_FILES = ["my_bib", "global_refs", "shared_bibliography"]
+```
+
+This will make the plugin search for files like `my_bib.bib`, `global_refs.bib`, etc.
+
+#### Bibliography File Priority
+
+The plugin searches for both individual and global bibliography files. If both types exist, all found bibliography files will be used by Pandoc. The order in which they are processed follows the order they are discovered during the recursive directory search.
 
 #### Known Issues with Citations
 
diff --git a/pelican/plugins/pandoc_reader/pandoc_reader.py b/pelican/plugins/pandoc_reader/pandoc_reader.py
@@ -390,17 +390,28 @@ def _check_if_toc(arguments):
                 table_of_contents = True
         return table_of_contents
 
-    @staticmethod
-    def _find_bibs(source_path):
+    def _find_bibs(self, source_path):
         """Find bibliographies recursively in the sourcepath given."""
         bib_files = []
         filename = os.path.splitext(os.path.basename(source_path))[0]
         directory_path = os.path.dirname(os.path.abspath(source_path))
+        
+        global_bib_names = self.settings.get(
+            "PANDOC_GLOBAL_BIB_FILES", 
+            ["_bibliography", "bibliography", "references"]
+        )
+        
         for root, _, files in os.walk(directory_path):
             for extension in VALID_BIB_EXTENSIONS:
                 bib_name = ".".join([filename, extension])
                 if bib_name in files:
                     bib_files.append(os.path.join(root, bib_name))
+                
+                for global_name in global_bib_names:
+                    global_bib_name = ".".join([global_name, extension])
+                    if global_bib_name in files:
+                        bib_files.append(os.path.join(root, global_bib_name))
+        
         return bib_files
 
     @staticmethod
diff --git a/pelican/plugins/pandoc_reader/test/markdown/_bibliography.bib b/pelican/plugins/pandoc_reader/test/markdown/_bibliography.bib
@@ -0,0 +1,16 @@
+@online{mann2019,
+url = {https://www.livescience.com/65033-what-is-string-theory.html},
+title = {{What Is String Theory?}},
+author = {Adam Mann},
+date = {2019-03-20},
+urldate = {2020-11-12}
+}
+
+@online{wood2019,
+url = {https://www.space.com/17594-string-theory.html},
+title = {{What Is String Theory?}},
+titleaddon = {Reference Article: A simplified explanation and brief history of string theory},
+author = {Charlie Wood},
+date = {2019-07-11},
+urldate = {2020-11-12}
+} 
diff --git a/pelican/plugins/pandoc_reader/test/markdown/bibliography.bib b/pelican/plugins/pandoc_reader/test/markdown/bibliography.bib
@@ -0,0 +1,17 @@
+@online{francis2019,
+url = {https://www.scientificamerican.com/article/is-string-theory-science/},
+title = {{Falsifiability and physics}},
+titleaddon = {Can a theory that isn't completely testable still be useful to physics?},
+author = {Matthew R Francis},
+date = {2019-04-23},
+urldate = {2020-11-12}
+}
+
+@online{alves2017,
+url = {https://metafact.io/factchecks/30-is-string-theory-falsifiable},
+title = {{Is String theory falsifiable?}},
+titleaddon = {Can a theory that isn't completely testable still be useful to physics?},
+author = {Rafael Alves Batista and Joel Primack},
+date = {circa 2017},
+urldate = {2020-11-12}
+} 
diff --git a/pelican/plugins/pandoc_reader/test/markdown/content_with_both_bibs.bib b/pelican/plugins/pandoc_reader/test/markdown/content_with_both_bibs.bib
@@ -0,0 +1,7 @@
+@online{jones2020,
+url = {https://www.thoughtco.com/what-is-string-theory-2699363},
+title = {{The Basics of String Theory}},
+author = {Andrew Zimmerman Jones},
+date = {2019-03-02},
+urldate = {2020-11-12}
+} 
diff --git a/pelican/plugins/pandoc_reader/test/markdown/content_with_both_bibs.md b/pelican/plugins/pandoc_reader/test/markdown/content_with_both_bibs.md
@@ -0,0 +1,9 @@
+---
+title: Content With Both Bibliographies
+author: My Author
+date: 2020-10-16
+summary: "This content has both individual and global bibliography files."
+---
+## Both Bibliographies Test
+
+This content references citations from both individual [@jones2020] and global [@mann2019] bibliography files. 
diff --git a/pelican/plugins/pandoc_reader/test/markdown/content_with_custom_global_bib.md b/pelican/plugins/pandoc_reader/test/markdown/content_with_custom_global_bib.md
@@ -0,0 +1,9 @@
+---
+title: Content With Custom Global Bibliography
+author: My Author
+date: 2020-10-16
+summary: "This content uses custom global bibliography files."
+---
+## Custom Global Bibliography Test
+
+This content references citations that should be found in custom global bibliography files [@siegel2015; @castelvecchi2016]. 
diff --git a/pelican/plugins/pandoc_reader/test/markdown/content_with_global_bib.md b/pelican/plugins/pandoc_reader/test/markdown/content_with_global_bib.md
@@ -0,0 +1,9 @@
+---
+title: Content With Global Bibliography
+author: My Author
+date: 2020-10-16
+summary: "This content uses global bibliography files."
+---
+## Global Bibliography Test
+
+This content references citations that should be found in global bibliography files [@mann2019; @wood2019]. 
diff --git a/pelican/plugins/pandoc_reader/test/markdown/content_with_multiple_global_bibs.md b/pelican/plugins/pandoc_reader/test/markdown/content_with_multiple_global_bibs.md
@@ -0,0 +1,9 @@
+---
+title: Content With Multiple Global Bibliographies
+author: My Author
+date: 2020-10-16
+summary: "This content uses multiple global bibliography files."
+---
+## Multiple Global Bibliographies Test
+
+This content references citations from multiple global bibliography files [@francis2019; @alves2017]. 
diff --git a/pelican/plugins/pandoc_reader/test/markdown/content_without_bib.md b/pelican/plugins/pandoc_reader/test/markdown/content_without_bib.md
@@ -0,0 +1,9 @@
+---
+title: Content Without Bibliography
+author: My Author
+date: 2020-10-16
+summary: "This content has no bibliography files."
+---
+## No Bibliography Test
+
+This content has no citations and no bibliography files should be found. 
diff --git a/pelican/plugins/pandoc_reader/test/markdown/my_bib.bib b/pelican/plugins/pandoc_reader/test/markdown/my_bib.bib
@@ -0,0 +1,16 @@
+@online{siegel2015,
+url = {https://www.forbes.com/sites/startswithabang/2015/12/23/why-string-theory-is-not-science/},
+title = {{Why String Theory Is Not A Scientific Theory}},
+author = {Ethan Siegel},
+date = {2015-12-23},
+urldate = {2020-11-12}
+}
+
+@online{castelvecchi2016,
+url = {https://www.nature.com/news/feuding-physicists-turn-to-philosophy-for-help-1.19076},
+title = {{Feuding physicists turn to philosophy for help}},
+titleaddon = {String theory is at the heart of a debate over the integrity of the scientific method itself},
+author = {Davide Castelvecchi},
+date = {2016-01-05},
+urldate = {2020-11-12}
+} 
diff --git a/pelican/plugins/pandoc_reader/test/test_global_bibliography.py b/pelican/plugins/pandoc_reader/test/test_global_bibliography.py
@@ -0,0 +1,115 @@
+"""Test global bibliography support with the pandoc-reader plugin."""
+
+import os
+import unittest
+
+from pelican.plugins.pandoc_reader import PandocReader
+from pelican.plugins.pandoc_reader.test.html.expected_html import (
+    HTML_WITH_CITATIONS,
+)
+from pelican.tests.support import get_settings
+
+DIR_PATH = os.path.dirname(__file__)
+TEST_CONTENT_PATH = os.path.abspath(os.path.join(DIR_PATH, "markdown"))
+
+PANDOC_ARGS = ["--mathjax", "--wrap=none", "--citeproc"]
+PANDOC_EXTENSIONS = ["+smart"]
+
+
+class TestGlobalBibliography(unittest.TestCase):
+    """Test cases for global bibliography functionality."""
+
+    def test_individual_bibliography_only(self):
+        """Test that individual bibliography files still work."""
+        settings = get_settings(
+            PANDOC_EXTENSIONS=PANDOC_EXTENSIONS,
+            PANDOC_ARGS=PANDOC_ARGS,
+        )
+
+        pandoc_reader = PandocReader(settings)
+        source_path = os.path.join(TEST_CONTENT_PATH, "valid_content_with_citation.md")
+        output, metadata = pandoc_reader.read(source_path)
+
+        self.assertEqual("Valid Content With Citation", str(metadata["title"]))
+        self.assertEqual("My Author", str(metadata["author"]))
+        self.assertEqual("2020-10-16 00:00:00", str(metadata["date"]))
+
+    def test_global_bibliography_default_names(self):
+        """Test that global bibliography files with default names are found."""
+        settings = get_settings(
+            PANDOC_EXTENSIONS=PANDOC_EXTENSIONS,
+            PANDOC_ARGS=PANDOC_ARGS,
+        )
+
+        pandoc_reader = PandocReader(settings)
+        source_path = os.path.join(TEST_CONTENT_PATH, "content_with_global_bib.md")
+        output, metadata = pandoc_reader.read(source_path)
+
+        self.assertEqual("Content With Global Bibliography", str(metadata["title"]))
+        self.assertEqual("My Author", str(metadata["author"]))
+        self.assertEqual("2020-10-16 00:00:00", str(metadata["date"]))
+
+    def test_custom_global_bibliography_names(self):
+        """Test that custom global bibliography file names work."""
+        settings = get_settings(
+            PANDOC_EXTENSIONS=PANDOC_EXTENSIONS,
+            PANDOC_ARGS=PANDOC_ARGS,
+            PANDOC_GLOBAL_BIB_FILES=["my_bib", "global_refs"],
+        )
+
+        pandoc_reader = PandocReader(settings)
+        source_path = os.path.join(TEST_CONTENT_PATH, "content_with_custom_global_bib.md")
+        output, metadata = pandoc_reader.read(source_path)
+
+        self.assertEqual("Content With Custom Global Bibliography", str(metadata["title"]))
+        self.assertEqual("My Author", str(metadata["author"]))
+        self.assertEqual("2020-10-16 00:00:00", str(metadata["date"]))
+
+    def test_both_individual_and_global_bibliography(self):
+        """Test that both individual and global bibliography files are found."""
+        settings = get_settings(
+            PANDOC_EXTENSIONS=PANDOC_EXTENSIONS,
+            PANDOC_ARGS=PANDOC_ARGS,
+        )
+
+        pandoc_reader = PandocReader(settings)
+        source_path = os.path.join(TEST_CONTENT_PATH, "content_with_both_bibs.md")
+        output, metadata = pandoc_reader.read(source_path)
+
+        self.assertEqual("Content With Both Bibliographies", str(metadata["title"]))
+        self.assertEqual("My Author", str(metadata["author"]))
+        self.assertEqual("2020-10-16 00:00:00", str(metadata["date"]))
+
+    def test_no_bibliography_files(self):
+        """Test behavior when no bibliography files exist."""
+        settings = get_settings(
+            PANDOC_EXTENSIONS=PANDOC_EXTENSIONS,
+            PANDOC_ARGS=PANDOC_ARGS,
+        )
+
+        pandoc_reader = PandocReader(settings)
+        source_path = os.path.join(TEST_CONTENT_PATH, "content_without_bib.md")
+        output, metadata = pandoc_reader.read(source_path)
+
+        self.assertEqual("Content Without Bibliography", str(metadata["title"]))
+        self.assertEqual("My Author", str(metadata["author"]))
+        self.assertEqual("2020-10-16 00:00:00", str(metadata["date"]))
+
+    def test_multiple_global_bibliography_files(self):
+        """Test that multiple global bibliography files are found."""
+        settings = get_settings(
+            PANDOC_EXTENSIONS=PANDOC_EXTENSIONS,
+            PANDOC_ARGS=PANDOC_ARGS,
+        )
+
+        pandoc_reader = PandocReader(settings)
+        source_path = os.path.join(TEST_CONTENT_PATH, "content_with_multiple_global_bibs.md")
+        output, metadata = pandoc_reader.read(source_path)
+
+        self.assertEqual("Content With Multiple Global Bibliographies", str(metadata["title"]))
+        self.assertEqual("My Author", str(metadata["author"]))
+        self.assertEqual("2020-10-16 00:00:00", str(metadata["date"]))
+
+
+if __name__ == "__main__":
+    unittest.main() 
diff --git a/pelicanconf_example.py b/pelicanconf_example.py
@@ -0,0 +1,56 @@
+# Example Pelican configuration file with global bibliography support
+# Copy this to your pelicanconf.py and customize as needed
+
+# Enable citations
+PANDOC_ARGS = [
+    "--citeproc",
+    "--csl=https://www.zotero.org/styles/ieee-with-url",
+    "--metadata=link-citations:false",
+    "--metadata=reference-section-title:References",
+]
+
+PANDOC_EXTENSIONS = ["+smart"]
+
+# Global bibliography files to search for
+# Default names are: ["_bibliography", "bibliography", "references"]
+PANDOC_GLOBAL_BIB_FILES = ["_bibliography", "bibliography", "references"]
+
+# Alternative custom global bibliography names
+# PANDOC_GLOBAL_BIB_FILES = ["my_bib", "global_refs", "shared_bibliography"]
+
+# Other common Pelican settings
+AUTHOR = "Your Name"
+SITENAME = "Your Site Name"
+SITEURL = ""
+
+# Path to your content directory
+PATH = "content"
+
+# Output directory
+OUTPUT_PATH = "output"
+
+# Theme settings (if using a theme)
+THEME = "theme"
+
+# URL settings
+ARTICLE_URL = "posts/{date:%Y}/{date:%m}/{date:%d}/{slug}/"
+ARTICLE_SAVE_AS = "posts/{date:%Y}/{date:%m}/{date:%d}/{slug}/index.html"
+
+PAGE_URL = "pages/{slug}/"
+PAGE_SAVE_AS = "pages/{slug}/index.html"
+
+# Feed settings
+FEED_ALL_ATOM = "feeds/all.atom.xml"
+CATEGORY_FEED_ATOM = "feeds/{slug}.atom.xml"
+
+# Social widget
+SOCIAL = (
+    ("GitHub", "https://github.com/yourusername"),
+    ("Twitter", "https://twitter.com/yourusername"),
+)
+
+# Pagination
+DEFAULT_PAGINATION = 10
+
+# Uncomment following line if you want document-relative URLs when developing
+# RELATIVE_URLS = True 
