0
# MkDocs BibTeX
1

2
An MkDocs plugin that enables managing citations with BibTeX format. It provides automatic bibliography generation, citation linking, and flexible formatting options for academic and research documentation workflows.
3

4
## Package Information
5

6
- **Package Name**: mkdocs-bibtex
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install mkdocs-bibtex`
10

11
## Core Imports
12

13
```python
14
from mkdocs_bibtex.plugin import BibTexPlugin
15
```
16

17
For direct usage of components:
18

19
```python
20
from mkdocs_bibtex.config import BibTexConfig
21
from mkdocs_bibtex.citation import Citation, CitationBlock, InlineReference
22
from mkdocs_bibtex.registry import SimpleRegistry, PandocRegistry
23
from mkdocs_bibtex.utils import tempfile_from_url, get_path_relative_to_mkdocs_yaml
24
```
25

26
## Basic Usage
27

28
### MkDocs Configuration
29

30
```yaml
31
plugins:
32
  - search
33
  - bibtex:
34
      bib_file: "refs.bib"
35
      csl_file: "citation-style.csl"  # optional
36
      footnote_format: "{key}"
37
      enable_inline_citations: true
38

39
markdown_extensions:
40
  - footnotes
41
```
42

43
### Citation Syntax in Markdown
44

45
```markdown
46
# My Document
47

48
This is a citation block: [@key1; @key2, pp. 100-120]
49

50
This is an inline citation: @key3
51

52
## Bibliography
53

54
\bibliography
55

56
## Full Bibliography (optional)
57

58
\full_bibliography
59
```
60

61
### Python API Usage
62

63
```python
64
from mkdocs_bibtex.plugin import BibTexPlugin
65
from mkdocs_bibtex.config import BibTexConfig
66

67
# Initialize plugin
68
plugin = BibTexPlugin()
69
plugin.load_config(options={"bib_file": "refs.bib"})
70
plugin.on_config(config)
71

72
# Process markdown with citations
73
markdown_text = "This cites [@example2020]."
74
processed = plugin.on_page_markdown(markdown_text, page, config, files)
75
```
76

77
## Architecture
78

79
The plugin follows a modular architecture with clear separation of concerns:
80

81
- **Plugin Layer**: MkDocs integration and lifecycle management
82
- **Configuration Layer**: Validated configuration schema and options
83
- **Citation Parser**: Extraction and parsing of citation syntax from markdown
84
- **Registry System**: Bibliography management with multiple formatting backends
85
- **Utility Layer**: File handling, URL processing, and path resolution
86

87
The registry system supports two backends:
88
- **SimpleRegistry**: Basic formatting using pybtex for simple use cases
89
- **PandocRegistry**: Advanced formatting with CSL support via Pandoc integration
90

91
## Capabilities
92

93
### Plugin Integration
94

95
Core MkDocs plugin functionality including configuration loading, lifecycle hooks, and markdown processing pipeline integration.
96

97
```python { .api }
98
class BibTexPlugin(BasePlugin[BibTexConfig]):
99
    def __init__(self): ...
100
    def on_startup(self, *, command, dirty): ...
101
    def on_config(self, config): ...
102
    def on_page_markdown(self, markdown, page, config, files): ...
103
```
104

105
[Plugin Integration](./plugin-integration.md)
106

107
### Citation Processing
108

109
Parsing and processing of citation syntax including citation blocks, inline references, and bibliography commands.
110

111
```python { .api }
112
class Citation:
113
    key: str
114
    prefix: str = ""
115
    suffix: str = ""
116
    
117
    @classmethod
118
    def from_markdown(cls, markdown: str) -> list[Citation]: ...
119

120
class CitationBlock:
121
    citations: list[Citation]
122
    raw: str = ""
123
    
124
    @classmethod
125
    def from_markdown(cls, markdown: str) -> list[CitationBlock]: ...
126

127
class InlineReference:
128
    key: str
129
    
130
    @classmethod
131
    def from_markdown(cls, markdown: str) -> list[InlineReference]: ...
132
```
133

134
[Citation Processing](./citation-processing.md)
135

136
### Bibliography Management
137

138
Registry system for managing bibliographic data, citation formatting, and reference text generation with support for multiple formatting backends.
139

140
```python { .api }
141
class ReferenceRegistry(ABC):
142
    def __init__(self, bib_files: list[str], footnote_format: str = "{key}"): ...
143
    def validate_citation_blocks(self, citation_blocks: list[CitationBlock]) -> None: ...
144
    def validate_inline_references(self, inline_references: list[InlineReference]) -> set[InlineReference]: ...
145
    def inline_text(self, citation_block: CitationBlock) -> str: ...
146
    def reference_text(self, citation: Union[Citation, InlineReference]) -> str: ...
147

148
class SimpleRegistry(ReferenceRegistry): ...
149
class PandocRegistry(ReferenceRegistry): ...
150
```
151

152
[Bibliography Management](./bibliography-management.md)
153

154
### Configuration Schema
155

156
Complete configuration options and validation schema for the MkDocs plugin.
157

158
```python { .api }
159
class BibTexConfig(base.Config):
160
    bib_file: config_options.Optional[config_options.Type[str]]
161
    bib_dir: config_options.Optional[config_options.Dir]
162
    csl_file: config_options.Optional[config_options.Type[str]]
163
    csl_file_encoding: config_options.Optional[config_options.Type[str]]
164
    bib_command: config_options.Type[str]
165
    full_bib_command: config_options.Type[str]
166
    bib_by_default: config_options.Type[bool]
167
    footnote_format: config_options.Type[str]
168
    enable_inline_citations: config_options.Type[bool]
169
```
170

171
[Configuration Schema](./configuration-schema.md)
172

173
### Utility Functions
174

175
File handling, URL processing, and path resolution utilities for remote BibTeX files and Zotero integration.
176

177
```python { .api }
178
def tempfile_from_url(name: str, url: str, suffix: str) -> str: ...
179
def tempfile_from_zotero_url(name: str, url: str, suffix: str) -> str: ...
180
def sanitize_zotero_query(url: str) -> str: ...
181
def get_path_relative_to_mkdocs_yaml(path: str, config: MkDocsConfig) -> str: ...
182
```
183

184
[Utility Functions](./utility-functions.md)
185

186
## Regular Expression Patterns
187

188
```python { .api }
189
import re
190

191
CITATION_REGEX: re.Pattern[str]
192
CITATION_BLOCK_REGEX: re.Pattern[str] 
193
EMAIL_REGEX: re.Pattern[str]
194
INLINE_REFERENCE_REGEX: re.Pattern[str]
195
```
196

197
## Types
198

199
```python { .api }
200
from typing import Union, List, Set, Optional, Dict, Tuple
201
from collections import OrderedDict
202
from pathlib import Path
203
from mkdocs.config.defaults import MkDocsConfig
204
from mkdocs.plugins import BasePlugin
205
from pybtex.database import BibliographyData
206
from pybtex.backends.markdown import Backend as MarkdownBackend
207
from pybtex.style.formatting.plain import Style as PlainStyle
208
```