0
# Bibliography Management
1
2
Registry system for managing bibliographic data, citation formatting, and reference text generation. The module provides an abstract base class and two concrete implementations for different formatting approaches.
3
4
## Capabilities
5
6
### ReferenceRegistry Abstract Base Class
7
8
Abstract base class that defines the interface for bibliography management systems.
9
10
```python { .api }
11
from abc import ABC, abstractmethod
12
from typing import Union
13
14
class ReferenceRegistry(ABC):
15
"""
16
A registry of references that can be used to format citations
17
"""
18
19
def __init__(self, bib_files: list[str], footnote_format: str = "{key}"):
20
"""
21
Initialize the registry with bibliography files.
22
23
Args:
24
bib_files (list[str]): List of paths to BibTeX files
25
footnote_format (str): Template for footnote formatting, must contain {key}
26
"""
27
28
@abstractmethod
29
def validate_citation_blocks(self, citation_blocks: list[CitationBlock]) -> None:
30
"""
31
Validates all citation blocks. Throws an error if any citation block is invalid.
32
33
Args:
34
citation_blocks (list[CitationBlock]): Citation blocks to validate
35
"""
36
37
@abstractmethod
38
def validate_inline_references(self, inline_references: list[InlineReference]) -> set[InlineReference]:
39
"""
40
Validates inline references and returns only the valid ones.
41
42
Args:
43
inline_references (list[InlineReference]): Inline references to validate
44
45
Returns:
46
set[InlineReference]: Set of valid inline references
47
"""
48
49
@abstractmethod
50
def inline_text(self, citation_block: CitationBlock) -> str:
51
"""
52
Retrieves the inline citation text for a citation block.
53
54
Args:
55
citation_block (CitationBlock): Citation block to format
56
57
Returns:
58
str: Formatted inline citation text
59
"""
60
61
@abstractmethod
62
def reference_text(self, citation: Union[Citation, InlineReference]) -> str:
63
"""
64
Retrieves the reference text for a citation or inline reference.
65
66
Args:
67
citation (Union[Citation, InlineReference]): Citation to format
68
69
Returns:
70
str: Formatted reference text for bibliography
71
"""
72
```
73
74
### SimpleRegistry Class
75
76
Simple reference registry using pybtex for basic formatting without CSL support.
77
78
```python { .api }
79
class SimpleRegistry(ReferenceRegistry):
80
"""Simple registry using pybtex formatting"""
81
82
def __init__(self, bib_files: list[str], footnote_format: str = "{key}"):
83
"""
84
Initialize simple registry with pybtex backend.
85
86
Args:
87
bib_files (list[str]): List of paths to BibTeX files
88
footnote_format (str): Template for footnote formatting
89
"""
90
91
def validate_citation_blocks(self, citation_blocks: list[CitationBlock]) -> None:
92
"""
93
Validates all citation blocks, logging warnings for unknown keys and unsupported features.
94
95
- Warns about unknown citation keys
96
- Warns about prefix/suffix usage (not supported in simple mode)
97
98
Args:
99
citation_blocks (list[CitationBlock]): Citation blocks to validate
100
"""
101
102
def validate_inline_references(self, inline_references: list[InlineReference]) -> set[InlineReference]:
103
"""
104
Validates inline references, returning only those with valid keys.
105
106
Args:
107
inline_references (list[InlineReference]): Inline references to validate
108
109
Returns:
110
set[InlineReference]: Valid inline references
111
"""
112
113
def inline_text(self, citation_block: CitationBlock) -> str:
114
"""
115
Generates inline citation text as footnote links.
116
117
Args:
118
citation_block (CitationBlock): Citation block to format
119
120
Returns:
121
str: Footnote links like "[^key1][^key2]"
122
"""
123
124
def reference_text(self, citation: Union[Citation, InlineReference]) -> str:
125
"""
126
Generates reference text using pybtex plain style.
127
128
Args:
129
citation (Union[Citation, InlineReference]): Citation to format
130
131
Returns:
132
str: Formatted bibliography entry
133
"""
134
```
135
136
### PandocRegistry Class
137
138
Advanced reference registry using Pandoc with CSL support for professional citation formatting.
139
140
```python { .api }
141
class PandocRegistry(ReferenceRegistry):
142
"""A registry that uses Pandoc to format citations"""
143
144
def __init__(self,
145
bib_files: list[str],
146
csl_file: str,
147
csl_file_encoding: Union[str, None],
148
footnote_format: str = "{key}"):
149
"""
150
Initialize Pandoc registry with CSL support.
151
152
Args:
153
bib_files (list[str]): List of paths to BibTeX files
154
csl_file (str): Path to CSL style file
155
csl_file_encoding (Union[str, None]): CSL file encoding
156
footnote_format (str): Template for footnote formatting
157
158
Raises:
159
ValueError: If Pandoc version is less than 2.11
160
"""
161
162
def validate_citation_blocks(self, citation_blocks: list[CitationBlock]) -> None:
163
"""
164
Validates citation blocks and pre-formats all citations using Pandoc.
165
166
Process:
167
1. Validate all citation keys exist in bibliography
168
2. Process unformatted citations through Pandoc
169
3. Cache formatted results for performance
170
171
Args:
172
citation_blocks (list[CitationBlock]): Citation blocks to validate and format
173
"""
174
175
def validate_inline_references(self, inline_references: list[InlineReference]) -> set[InlineReference]:
176
"""
177
Validates inline references and processes them through Pandoc.
178
179
Args:
180
inline_references (list[InlineReference]): Inline references to validate
181
182
Returns:
183
set[InlineReference]: Valid inline references
184
"""
185
186
def inline_text(self, citation_block: CitationBlock) -> str:
187
"""
188
Get the inline text for a citation block from Pandoc processing.
189
190
For inline CSL styles: returns both inline citation and footnote links
191
For footnote CSL styles: returns only footnote links
192
193
Args:
194
citation_block (CitationBlock): Citation block to format
195
196
Returns:
197
str: Formatted inline citation text
198
"""
199
200
def reference_text(self, citation: Union[Citation, InlineReference]) -> str:
201
"""
202
Returns cached reference text from Pandoc processing.
203
204
Args:
205
citation (Union[Citation, InlineReference]): Citation to get reference for
206
207
Returns:
208
str: Formatted bibliography entry
209
"""
210
211
@cached_property
212
def bib_data_bibtex(self) -> str:
213
"""
214
Convert bibliography data to BibTeX format string.
215
216
Returns:
217
str: Bibliography data in BibTeX format
218
"""
219
```
220
221
### Registry Attributes
222
223
Both registry implementations maintain bibliography data and formatting state.
224
225
```python { .api }
226
# Common attributes
227
bib_data: BibliographyData # Parsed bibliography data from pybtex
228
footnote_format: str # Template for footnote formatting
229
230
# SimpleRegistry specific
231
style: PlainStyle # pybtex plain formatting style
232
backend: MarkdownBackend # pybtex markdown backend
233
234
# PandocRegistry specific
235
csl_file: str # Path to CSL style file
236
_inline_cache: dict[str, str] # Cache for formatted inline citations
237
_reference_cache: dict[str, str] # Cache for formatted reference text
238
_is_inline: bool # Whether CSL style uses inline format
239
```
240
241
## Usage Examples
242
243
### SimpleRegistry Usage
244
245
```python
246
from mkdocs_bibtex.registry import SimpleRegistry
247
from mkdocs_bibtex.citation import CitationBlock
248
249
# Initialize simple registry
250
registry = SimpleRegistry(
251
bib_files=["refs.bib"],
252
footnote_format="{key}"
253
)
254
255
# Process citations
256
citation_blocks = CitationBlock.from_markdown("[@smith2020]")
257
registry.validate_citation_blocks(citation_blocks)
258
259
# Generate inline text
260
inline_text = registry.inline_text(citation_blocks[0])
261
print(inline_text) # "[^smith2020]"
262
263
# Generate reference text
264
ref_text = registry.reference_text(citation_blocks[0].citations[0])
265
print(ref_text) # "Smith, J. Title. Journal, 2020."
266
```
267
268
### PandocRegistry Usage
269
270
```python
271
from mkdocs_bibtex.registry import PandocRegistry
272
from mkdocs_bibtex.citation import CitationBlock
273
274
# Initialize Pandoc registry with CSL
275
registry = PandocRegistry(
276
bib_files=["refs.bib"],
277
csl_file="apa.csl",
278
csl_file_encoding=None,
279
footnote_format="{key}"
280
)
281
282
# Process citations (includes Pandoc formatting)
283
citation_blocks = CitationBlock.from_markdown("[@smith2020, pp. 100-120]")
284
registry.validate_citation_blocks(citation_blocks)
285
286
# Generate formatted inline text
287
inline_text = registry.inline_text(citation_blocks[0])
288
print(inline_text) # "(Smith, 2020, pp. 100-120)[^smith2020]"
289
290
# Generate formatted reference text
291
ref_text = registry.reference_text(citation_blocks[0].citations[0])
292
print(ref_text) # "Smith, J. (2020). Title. Journal, 15(3), 123-145."
293
```
294
295
### Registry Selection Logic
296
297
```python
298
from mkdocs_bibtex.registry import SimpleRegistry, PandocRegistry
299
300
def create_registry(bib_files, csl_file=None, footnote_format="{key}"):
301
"""Create appropriate registry based on CSL availability."""
302
303
if csl_file:
304
return PandocRegistry(
305
bib_files=bib_files,
306
csl_file=csl_file,
307
csl_file_encoding=None,
308
footnote_format=footnote_format
309
)
310
else:
311
return SimpleRegistry(
312
bib_files=bib_files,
313
footnote_format=footnote_format
314
)
315
316
# Usage in plugin
317
registry = create_registry(
318
bib_files=["refs.bib"],
319
csl_file="chicago.csl" if use_csl else None
320
)
321
```
322
323
## CSL Style Detection
324
325
The PandocRegistry automatically detects CSL style types:
326
327
### Inline Styles
328
329
CSL files with `citation-format="author-date"` produce inline citations:
330
331
```
332
According to (Smith, 2020), the method works.
333
```
334
335
### Footnote Styles
336
337
CSL files with numeric or other formats produce footnote-only citations:
338
339
```
340
According to Smith¹, the method works.
341
```
342
343
## Caching System
344
345
The PandocRegistry implements sophisticated caching:
346
347
- **Inline Cache**: Stores formatted inline citation text
348
- **Reference Cache**: Stores formatted bibliography entries
349
- **Incremental Processing**: Only processes new citations
350
- **Performance Optimization**: Avoids redundant Pandoc calls
351
- **Memory Management**: Efficient storage of formatted results
352
353
## Error Handling
354
355
### Common Error Conditions
356
357
- **Missing Bibliography Keys**: Logged as warnings, citations marked as invalid
358
- **Pandoc Version Compatibility**: Raises ValueError for unsupported Pandoc versions
359
- **CSL File Errors**: Logged as warnings, falls back to default formatting
360
- **Network Errors**: Handled by utility functions for remote files
361
- **Malformed BibTeX**: Reported through pybtex error handling
362
363
### Validation Patterns
364
365
```python
366
# Citation validation
367
try:
368
registry.validate_citation_blocks(citation_blocks)
369
except Exception as e:
370
logger.error(f"Citation validation failed: {e}")
371
372
# Reference existence check
373
valid_refs = registry.validate_inline_references(inline_refs)
374
invalid_count = len(inline_refs) - len(valid_refs)
375
if invalid_count > 0:
376
logger.warning(f"Found {invalid_count} invalid inline references")
377
```