Configuration Schema

from mkdocs.config import base, config_options

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

    Options:
        bib_file (string): path or url to a single bibtex file for entries,
                           url example: https://api.zotero.org/*/items?format=bibtex
        bib_dir (string): path to a directory of bibtex files for entries
        bib_command (string): command to place a bibliography relevant to just that file
                              defaults to \bibliography
        bib_by_default (bool): automatically appends bib_command to markdown pages
                               by default, defaults to true
        full_bib_command (string): command to place a full bibliography of all references
        csl_file (string, optional): path or url to a CSL file, relative to mkdocs.yml.
        footnote_format (string): format for the footnote number, defaults to "{key}"
        enable_inline_citations (bool): enable inline citations, these can clash with a lot of other features
    """
    
    # Input files
    bib_file: config_options.Optional[config_options.Type[str]]
    bib_dir: config_options.Optional[config_options.Dir]
    csl_file: config_options.Optional[config_options.Type[str]]
    csl_file_encoding: config_options.Optional[config_options.Type[str]]
    
    # Commands
    bib_command: config_options.Type[str]
    full_bib_command: config_options.Type[str]
    
    # Settings
    bib_by_default: config_options.Type[bool]
    footnote_format: config_options.Type[str]
    enable_inline_citations: config_options.Type[bool]

bib_file = config_options.Optional(config_options.Type(str))
"""
Optional path or URL to a single BibTeX file.

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

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

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

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

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

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

Note: Enables advanced formatting via Pandoc registry
"""

csl_file_encoding = config_options.Optional(config_options.Type(str))
"""
Optional encoding for CSL file.

- Defaults to platform encoding
- Remote CSL files use UTF-8 encoding
- Only applies to local CSL files
"""

bib_command = config_options.Type(str, default="\\bibliography")
"""
Command to insert bibliography for current page.

Default: "\\bibliography"

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

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

Default: "\\full_bibliography"

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

bib_by_default = config_options.Type(bool, default=True)
"""
Automatically append bibliography to every page.

Default: True

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

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

Default: "{key}"

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

Examples:
- "{key}" -> "smith2020"
- "cite_{key}" -> "cite_smith2020"  
- "{key}_ref" -> "smith2020_ref"
"""

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

Default: True

When enabled, processes @key syntax outside of citation blocks.
May conflict with other markdown syntax that uses @ symbols.
"""

plugins:
  - bibtex:
      bib_file: "references.bib"
      
markdown_extensions:
  - footnotes

plugins:
  - bibtex:
      bib_file: "https://api.zotero.org/groups/12345/items?format=bibtex"
      csl_file: "styles/chicago-author-date.csl"
      bib_command: "\\references"
      full_bib_command: "\\complete_bibliography"
      bib_by_default: false
      footnote_format: "ref_{key}"
      enable_inline_citations: false
      
markdown_extensions:
  - footnotes

plugins:
  - bibtex:
      bib_dir: "bibliography/"
      csl_file: "https://raw.githubusercontent.com/citation-style-language/styles/master/apa.csl"
      bib_by_default: true
      
markdown_extensions:
  - footnotes

plugins:
  - bibtex:
      bib_file: "refs.bib"
      # All other options use defaults
      
markdown_extensions:
  - footnotes

# At least one bibliography source must be specified
if not config.bib_file and not config.bib_dir:
    raise ConfigurationError("Must supply a bibtex file or directory for bibtex files")

# footnote_format must contain {key} placeholder
if "{key}" not in config.footnote_format:
    raise ConfigurationError("Must include `{key}` placeholder in footnote_format")

# bib_dir must exist if specified (handled by config_options.Dir)
# Local files are validated when accessed
# Remote URLs are validated during download

from mkdocs_bibtex.utils import get_path_relative_to_mkdocs_yaml

# Resolve relative paths
bib_file_path = get_path_relative_to_mkdocs_yaml(config.bib_file, mkdocs_config)
csl_file_path = get_path_relative_to_mkdocs_yaml(config.csl_file, mkdocs_config)

import validators

# URL detection
is_url = validators.url(config.bib_file)
if is_url:
    cached_file = tempfile_from_url("bib file", config.bib_file, ".bib")

def select_registry(config):
    if config.csl_file:
        return PandocRegistry(
            bib_files=bib_files,
            csl_file=config.csl_file,
            csl_file_encoding=config.csl_file_encoding,
            footnote_format=config.footnote_format
        )
    else:
        return SimpleRegistry(
            bib_files=bib_files,
            footnote_format=config.footnote_format
        )

from mkdocs.exceptions import ConfigurationError

# Invalid configuration raises ConfigurationError
try:
    plugin.load_config(invalid_options)
except ConfigurationError as e:
    print(f"Configuration error: {e}")

# Missing local files
if not os.path.exists(bib_file_path):
    logger.error(f"Bibliography file not found: {bib_file_path}")

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