tessl/pypi-mkdocs-bibtex

An MkDocs plugin that enables managing citations with BibTex

—

Pending

Overview

Eval results

Files

Plugin Integration

Name: tessl/pypi-mkdocs-bibtex
Author: tessl

Core MkDocs plugin functionality that integrates BibTeX citation management into the MkDocs build process. The plugin implements the MkDocs plugin lifecycle hooks to process citations during site generation.

Capabilities

BibTexPlugin Class

Main plugin class that inherits from MkDocs BasePlugin and implements the BibTeX citation processing functionality.

class BibTexPlugin(BasePlugin[BibTexConfig]):
    """
    Allows the use of bibtex in markdown content for MKDocs.
    """
    
    def __init__(self):
        """Initialize the plugin with empty state."""
        
    def on_startup(self, *, command, dirty):
        """
        Having on_startup() tells mkdocs to keep the plugin object upon rebuilds.
        
        Args:
            command: The MkDocs command being run
            dirty: Whether this is a dirty rebuild
        """
        
    def on_config(self, config):
        """
        Loads bibliography on load of config.
        
        Args:
            config: MkDocs configuration object
            
        Returns:
            Updated config object
            
        Raises:
            ConfigurationError: If bibliography files are not configured properly
        """
        
    def on_page_markdown(self, markdown, page, config, files):
        """
        Parses the markdown for each page, extracting the bibtex references.
        
        Process:
        1. Finds all cite keys (may include multiple citation references)
        2. Convert all cite keys to citation objects
        3. Insert formatted cite keys into text
        4. Insert the bibliography into the markdown
        5. Insert the full bibliography into the markdown
        6. Process inline references if enabled
        
        Args:
            markdown (str): The raw markdown content
            page: MkDocs page object
            config: MkDocs configuration object  
            files: MkDocs files collection
            
        Returns:
            str: Processed markdown content with citations replaced
        """

Plugin Attributes

The plugin maintains state across the build process through several key attributes.

# Plugin instance attributes
bib_data: Optional[BibliographyData]  # Parsed bibliography data
all_references: OrderedDict  # All references collected during build
last_configured: Optional[float]  # Timestamp of last configuration
registry: Optional[Union[SimpleRegistry, PandocRegistry]]  # Reference formatting registry
csl_file: Optional[str]  # Path to CSL style file

Usage Examples

Basic Plugin Initialization

from mkdocs_bibtex.plugin import BibTexPlugin

# Create plugin instance
plugin = BibTexPlugin()

# Load configuration
plugin.load_config(options={
    "bib_file": "references.bib",
    "footnote_format": "{key}"
})

# Initialize with MkDocs config
plugin.on_config(mkdocs_config)

Processing Markdown Content

# Input markdown with citations
markdown_input = '''
# My Document

This references [@smith2020; @jones2019].

\bibliography
'''

# Process through plugin
processed_markdown = plugin.on_page_markdown(
    markdown_input, 
    page_object, 
    config_object, 
    files_object
)

# Result includes formatted citations and bibliography
print(processed_markdown)

Configuration with URL-based Bibliography

plugin = BibTexPlugin()
plugin.load_config(options={
    "bib_file": "https://api.zotero.org/groups/12345/items?format=bibtex",
    "csl_file": "https://raw.githubusercontent.com/citation-style-language/styles/master/apa.csl",
    "footnote_format": "{key}"
})

Error Handling

The plugin handles various error conditions during processing:

Missing Bibliography Files: Raises ConfigurationError if no bib_file or bib_dir is configured
Invalid Footnote Format: Raises ConfigurationError if footnote_format doesn't contain {key} placeholder
Unknown Citation Keys: Logs warnings for citations that don't exist in bibliography
Network Errors: Retries URL downloads up to 3 times before failing
Pandoc Compatibility: Validates Pandoc version requirements for advanced formatting

Integration Points

MkDocs Lifecycle Hooks

The plugin integrates with MkDocs at three key points:

Startup (on_startup): Ensures plugin persistence across rebuilds
Configuration (on_config): Loads and validates bibliography data
Page Processing (on_page_markdown): Processes citations in each markdown file