0
# Configuration Schema
1

2
Complete configuration options and validation schema for the MkDocs BibTeX plugin. The configuration system uses MkDocs' built-in configuration framework to provide type-safe, validated options.
3

4
## Capabilities
5

6
### BibTexConfig Class
7

8
Configuration schema class that defines all available options for the BibTeX plugin.
9

10
```python { .api }
11
from mkdocs.config import base, config_options
12

13
class BibTexConfig(base.Config):
14
    """
15
    Configuration of the BibTex pluging for mkdocs.
16

17
    Options:
18
        bib_file (string): path or url to a single bibtex file for entries,
19
                           url example: https://api.zotero.org/*/items?format=bibtex
20
        bib_dir (string): path to a directory of bibtex files for entries
21
        bib_command (string): command to place a bibliography relevant to just that file
22
                              defaults to \bibliography
23
        bib_by_default (bool): automatically appends bib_command to markdown pages
24
                               by default, defaults to true
25
        full_bib_command (string): command to place a full bibliography of all references
26
        csl_file (string, optional): path or url to a CSL file, relative to mkdocs.yml.
27
        footnote_format (string): format for the footnote number, defaults to "{key}"
28
        enable_inline_citations (bool): enable inline citations, these can clash with a lot of other features
29
    """
30
    
31
    # Input files
32
    bib_file: config_options.Optional[config_options.Type[str]]
33
    bib_dir: config_options.Optional[config_options.Dir]
34
    csl_file: config_options.Optional[config_options.Type[str]]
35
    csl_file_encoding: config_options.Optional[config_options.Type[str]]
36
    
37
    # Commands
38
    bib_command: config_options.Type[str]
39
    full_bib_command: config_options.Type[str]
40
    
41
    # Settings
42
    bib_by_default: config_options.Type[bool]
43
    footnote_format: config_options.Type[str]
44
    enable_inline_citations: config_options.Type[bool]
45
```
46

47
## Configuration Options
48

49
### Input File Options
50

51
Options for specifying bibliography data sources.
52

53
```python { .api }
54
bib_file = config_options.Optional(config_options.Type(str))
55
"""
56
Optional path or URL to a single BibTeX file.
57

58
Examples:
59
- Local file: "references.bib" 
60
- Absolute path: "/path/to/refs.bib"
61
- Remote URL: "https://example.com/refs.bib"
62
- Zotero API: "https://api.zotero.org/groups/12345/items?format=bibtex"
63

64
Note: Path is resolved relative to mkdocs.yml location
65
"""
66

67
bib_dir = config_options.Optional(config_options.Dir(exists=True))
68
"""
69
Optional path to directory containing BibTeX files.
70

71
- Scans recursively for *.bib files
72
- Must be existing directory
73
- Path resolved relative to mkdocs.yml location
74
- Alternative to bib_file for multiple bibliography sources
75
"""
76

77
csl_file = config_options.Optional(config_options.Type(str))
78
"""
79
Optional path or URL to CSL (Citation Style Language) file.
80

81
Examples:
82
- Local file: "styles/apa.csl"
83
- Remote URL: "https://raw.githubusercontent.com/citation-style-language/styles/master/apa.csl"
84

85
Note: Enables advanced formatting via Pandoc registry
86
"""
87

88
csl_file_encoding = config_options.Optional(config_options.Type(str))
89
"""
90
Optional encoding for CSL file.
91

92
- Defaults to platform encoding
93
- Remote CSL files use UTF-8 encoding
94
- Only applies to local CSL files
95
"""
96
```
97

98
### Command Options
99

100
Options for bibliography insertion commands in markdown.
101

102
```python { .api }
103
bib_command = config_options.Type(str, default="\\bibliography")
104
"""
105
Command to insert bibliography for current page.
106

107
Default: "\\bibliography"
108

109
The command is replaced with formatted bibliography entries for citations
110
found on the current page.
111
"""
112

113
full_bib_command = config_options.Type(str, default="\\full_bibliography") 
114
"""
115
Command to insert complete bibliography.
116

117
Default: "\\full_bibliography"
118

119
The command is replaced with all bibliography entries from loaded BibTeX files,
120
regardless of whether they are cited on the current page.
121
"""
122
```
123

124
### Behavior Settings
125

126
Options controlling plugin behavior and citation processing.
127

128
```python { .api }
129
bib_by_default = config_options.Type(bool, default=True)
130
"""
131
Automatically append bibliography to every page.
132

133
Default: True
134

135
When enabled, automatically adds bib_command to the end of every markdown 
136
page, ensuring bibliographies appear without manual insertion.
137
"""
138

139
footnote_format = config_options.Type(str, default="{key}")
140
"""
141
Template for footnote formatting.
142

143
Default: "{key}"
144

145
Must contain {key} placeholder which is replaced with citation key.
146
Used for generating footnote links and identifiers.
147

148
Examples:
149
- "{key}" -> "smith2020"
150
- "cite_{key}" -> "cite_smith2020"  
151
- "{key}_ref" -> "smith2020_ref"
152
"""
153

154
enable_inline_citations = config_options.Type(bool, default=True)
155
"""
156
Enable processing of inline citations.
157

158
Default: True
159

160
When enabled, processes @key syntax outside of citation blocks.
161
May conflict with other markdown syntax that uses @ symbols.
162
"""
163
```
164

165
## Usage Examples
166

167
### Basic Configuration
168

169
```yaml
170
plugins:
171
  - bibtex:
172
      bib_file: "references.bib"
173
      
174
markdown_extensions:
175
  - footnotes
176
```
177

178
### Advanced Configuration
179

180
```yaml
181
plugins:
182
  - bibtex:
183
      bib_file: "https://api.zotero.org/groups/12345/items?format=bibtex"
184
      csl_file: "styles/chicago-author-date.csl"
185
      bib_command: "\\references"
186
      full_bib_command: "\\complete_bibliography"
187
      bib_by_default: false
188
      footnote_format: "ref_{key}"
189
      enable_inline_citations: false
190
      
191
markdown_extensions:
192
  - footnotes
193
```
194

195
### Directory-based Configuration
196

197
```yaml
198
plugins:
199
  - bibtex:
200
      bib_dir: "bibliography/"
201
      csl_file: "https://raw.githubusercontent.com/citation-style-language/styles/master/apa.csl"
202
      bib_by_default: true
203
      
204
markdown_extensions:
205
  - footnotes
206
```
207

208
### Minimal Configuration
209

210
```yaml
211
plugins:
212
  - bibtex:
213
      bib_file: "refs.bib"
214
      # All other options use defaults
215
      
216
markdown_extensions:
217
  - footnotes
218
```
219

220
## Configuration Validation
221

222
The configuration system provides automatic validation:
223

224
### Required Dependencies
225

226
```python
227
# At least one bibliography source must be specified
228
if not config.bib_file and not config.bib_dir:
229
    raise ConfigurationError("Must supply a bibtex file or directory for bibtex files")
230
```
231

232
### Footnote Format Validation
233

234
```python
235
# footnote_format must contain {key} placeholder
236
if "{key}" not in config.footnote_format:
237
    raise ConfigurationError("Must include `{key}` placeholder in footnote_format")
238
```
239

240
### File Existence Validation
241

242
```python
243
# bib_dir must exist if specified (handled by config_options.Dir)
244
# Local files are validated when accessed
245
# Remote URLs are validated during download
246
```
247

248
## Environment Integration
249

250
### Path Resolution
251

252
All local file paths are resolved relative to the MkDocs configuration file:
253

254
```python
255
from mkdocs_bibtex.utils import get_path_relative_to_mkdocs_yaml
256

257
# Resolve relative paths
258
bib_file_path = get_path_relative_to_mkdocs_yaml(config.bib_file, mkdocs_config)
259
csl_file_path = get_path_relative_to_mkdocs_yaml(config.csl_file, mkdocs_config)
260
```
261

262
### Remote File Handling
263

264
Remote URLs are automatically detected and cached:
265

266
```python
267
import validators
268

269
# URL detection
270
is_url = validators.url(config.bib_file)
271
if is_url:
272
    cached_file = tempfile_from_url("bib file", config.bib_file, ".bib")
273
```
274

275
### Registry Selection
276

277
Configuration determines which registry implementation to use:
278

279
```python
280
def select_registry(config):
281
    if config.csl_file:
282
        return PandocRegistry(
283
            bib_files=bib_files,
284
            csl_file=config.csl_file,
285
            csl_file_encoding=config.csl_file_encoding,
286
            footnote_format=config.footnote_format
287
        )
288
    else:
289
        return SimpleRegistry(
290
            bib_files=bib_files,
291
            footnote_format=config.footnote_format
292
        )
293
```
294

295
## Configuration Inheritance
296

297
MkDocs configuration follows standard inheritance patterns:
298

299
1. **Default Values**: Built-in defaults from configuration schema
300
2. **Global Config**: Values from mkdocs.yml plugin configuration  
301
3. **Runtime Overrides**: Any programmatic configuration changes
302

303
## Error Handling
304

305
### Configuration Errors
306

307
```python
308
from mkdocs.exceptions import ConfigurationError
309

310
# Invalid configuration raises ConfigurationError
311
try:
312
    plugin.load_config(invalid_options)
313
except ConfigurationError as e:
314
    print(f"Configuration error: {e}")
315
```
316

317
### File Access Errors
318

319
```python
320
# Missing local files
321
if not os.path.exists(bib_file_path):
322
    logger.error(f"Bibliography file not found: {bib_file_path}")
323

324
# Network errors for remote files  
325
try:
326
    tempfile_from_url("bib file", remote_url, ".bib")
327
except RuntimeError as e:
328
    logger.error(f"Failed to download bibliography: {e}")
329
```