0
# Plugin Integration
1

2
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.
3

4
## Capabilities
5

6
### BibTexPlugin Class
7

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

10
```python { .api }
11
class BibTexPlugin(BasePlugin[BibTexConfig]):
12
    """
13
    Allows the use of bibtex in markdown content for MKDocs.
14
    """
15
    
16
    def __init__(self):
17
        """Initialize the plugin with empty state."""
18
        
19
    def on_startup(self, *, command, dirty):
20
        """
21
        Having on_startup() tells mkdocs to keep the plugin object upon rebuilds.
22
        
23
        Args:
24
            command: The MkDocs command being run
25
            dirty: Whether this is a dirty rebuild
26
        """
27
        
28
    def on_config(self, config):
29
        """
30
        Loads bibliography on load of config.
31
        
32
        Args:
33
            config: MkDocs configuration object
34
            
35
        Returns:
36
            Updated config object
37
            
38
        Raises:
39
            ConfigurationError: If bibliography files are not configured properly
40
        """
41
        
42
    def on_page_markdown(self, markdown, page, config, files):
43
        """
44
        Parses the markdown for each page, extracting the bibtex references.
45
        
46
        Process:
47
        1. Finds all cite keys (may include multiple citation references)
48
        2. Convert all cite keys to citation objects
49
        3. Insert formatted cite keys into text
50
        4. Insert the bibliography into the markdown
51
        5. Insert the full bibliography into the markdown
52
        6. Process inline references if enabled
53
        
54
        Args:
55
            markdown (str): The raw markdown content
56
            page: MkDocs page object
57
            config: MkDocs configuration object  
58
            files: MkDocs files collection
59
            
60
        Returns:
61
            str: Processed markdown content with citations replaced
62
        """
63
```
64

65
### Plugin Attributes
66

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

69
```python { .api }
70
# Plugin instance attributes
71
bib_data: Optional[BibliographyData]  # Parsed bibliography data
72
all_references: OrderedDict  # All references collected during build
73
last_configured: Optional[float]  # Timestamp of last configuration
74
registry: Optional[Union[SimpleRegistry, PandocRegistry]]  # Reference formatting registry
75
csl_file: Optional[str]  # Path to CSL style file
76
```
77

78
## Usage Examples
79

80
### Basic Plugin Initialization
81

82
```python
83
from mkdocs_bibtex.plugin import BibTexPlugin
84

85
# Create plugin instance
86
plugin = BibTexPlugin()
87

88
# Load configuration
89
plugin.load_config(options={
90
    "bib_file": "references.bib",
91
    "footnote_format": "{key}"
92
})
93

94
# Initialize with MkDocs config
95
plugin.on_config(mkdocs_config)
96
```
97

98
### Processing Markdown Content
99

100
```python
101
# Input markdown with citations
102
markdown_input = '''
103
# My Document
104

105
This references [@smith2020; @jones2019].
106

107
\bibliography
108
'''
109

110
# Process through plugin
111
processed_markdown = plugin.on_page_markdown(
112
    markdown_input, 
113
    page_object, 
114
    config_object, 
115
    files_object
116
)
117

118
# Result includes formatted citations and bibliography
119
print(processed_markdown)
120
```
121

122
### Configuration with URL-based Bibliography
123

124
```python
125
plugin = BibTexPlugin()
126
plugin.load_config(options={
127
    "bib_file": "https://api.zotero.org/groups/12345/items?format=bibtex",
128
    "csl_file": "https://raw.githubusercontent.com/citation-style-language/styles/master/apa.csl",
129
    "footnote_format": "{key}"
130
})
131
```
132

133
## Error Handling
134

135
The plugin handles various error conditions during processing:
136

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

143
## Integration Points
144

145
### MkDocs Lifecycle Hooks
146

147
The plugin integrates with MkDocs at three key points:
148

149
1. **Startup** (`on_startup`): Ensures plugin persistence across rebuilds
150
2. **Configuration** (`on_config`): Loads and validates bibliography data
151
3. **Page Processing** (`on_page_markdown`): Processes citations in each markdown file
152

153
### Dependencies Integration
154

155
- **pybtex**: Bibliography parsing and basic formatting
156
- **pypandoc**: Advanced citation formatting with CSL support
157
- **requests**: Remote file downloading for URLs and Zotero API
158
- **validators**: URL validation for remote bibliography files
159
- **MkDocs**: Core plugin framework and configuration system
160

161
### File System Integration
162

163
The plugin handles various file sources:
164

165
- Local BibTeX files (relative to `mkdocs.yml`)
166
- Remote BibTeX URLs (cached as temporary files)
167
- Zotero API integration with pagination support
168
- CSL style files (local or remote)
169
- Bibliography directories (recursive `.bib` file discovery)