or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

bibliography-management.mdcitation-processing.mdconfiguration-schema.mdindex.mdplugin-integration.mdutility-functions.md
tile.json

tessl/pypi-mkdocs-bibtex

An MkDocs plugin that enables managing citations with BibTex

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/mkdocs-bibtex@4.4.x

To install, run

npx @tessl/cli install tessl/pypi-mkdocs-bibtex@4.4.0

index.mddocs/

MkDocs BibTeX

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.

Package Information

  • Package Name: mkdocs-bibtex
  • Package Type: pypi
  • Language: Python
  • Installation: pip install mkdocs-bibtex

Core Imports

from mkdocs_bibtex.plugin import BibTexPlugin

For direct usage of components:

from mkdocs_bibtex.config import BibTexConfig
from mkdocs_bibtex.citation import Citation, CitationBlock, InlineReference
from mkdocs_bibtex.registry import SimpleRegistry, PandocRegistry
from mkdocs_bibtex.utils import tempfile_from_url, get_path_relative_to_mkdocs_yaml

Basic Usage

MkDocs Configuration

plugins:
  - search
  - bibtex:
      bib_file: "refs.bib"
      csl_file: "citation-style.csl"  # optional
      footnote_format: "{key}"
      enable_inline_citations: true

markdown_extensions:
  - footnotes

Citation Syntax in Markdown

# My Document

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

This is an inline citation: @key3

## Bibliography

\bibliography

## Full Bibliography (optional)

\full_bibliography

Python API Usage

from mkdocs_bibtex.plugin import BibTexPlugin
from mkdocs_bibtex.config import BibTexConfig

# Initialize plugin
plugin = BibTexPlugin()
plugin.load_config(options={"bib_file": "refs.bib"})
plugin.on_config(config)

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

Architecture

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

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

The registry system supports two backends:

  • SimpleRegistry: Basic formatting using pybtex for simple use cases
  • PandocRegistry: Advanced formatting with CSL support via Pandoc integration

Capabilities

Plugin Integration

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

class BibTexPlugin(BasePlugin[BibTexConfig]):
    def __init__(self): ...
    def on_startup(self, *, command, dirty): ...
    def on_config(self, config): ...
    def on_page_markdown(self, markdown, page, config, files): ...

Plugin Integration

Citation Processing

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

class Citation:
    key: str
    prefix: str = ""
    suffix: str = ""
    
    @classmethod
    def from_markdown(cls, markdown: str) -> list[Citation]: ...

class CitationBlock:
    citations: list[Citation]
    raw: str = ""
    
    @classmethod
    def from_markdown(cls, markdown: str) -> list[CitationBlock]: ...

class InlineReference:
    key: str
    
    @classmethod
    def from_markdown(cls, markdown: str) -> list[InlineReference]: ...

Citation Processing

Bibliography Management

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

class ReferenceRegistry(ABC):
    def __init__(self, bib_files: list[str], footnote_format: str = "{key}"): ...
    def validate_citation_blocks(self, citation_blocks: list[CitationBlock]) -> None: ...
    def validate_inline_references(self, inline_references: list[InlineReference]) -> set[InlineReference]: ...
    def inline_text(self, citation_block: CitationBlock) -> str: ...
    def reference_text(self, citation: Union[Citation, InlineReference]) -> str: ...

class SimpleRegistry(ReferenceRegistry): ...
class PandocRegistry(ReferenceRegistry): ...

Bibliography Management

Configuration Schema

Complete configuration options and validation schema for the MkDocs plugin.

class BibTexConfig(base.Config):
    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]]
    bib_command: config_options.Type[str]
    full_bib_command: config_options.Type[str]
    bib_by_default: config_options.Type[bool]
    footnote_format: config_options.Type[str]
    enable_inline_citations: config_options.Type[bool]

Configuration Schema

Utility Functions

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

def tempfile_from_url(name: str, url: str, suffix: str) -> str: ...
def tempfile_from_zotero_url(name: str, url: str, suffix: str) -> str: ...
def sanitize_zotero_query(url: str) -> str: ...
def get_path_relative_to_mkdocs_yaml(path: str, config: MkDocsConfig) -> str: ...

Utility Functions

Regular Expression Patterns

import re

CITATION_REGEX: re.Pattern[str]
CITATION_BLOCK_REGEX: re.Pattern[str] 
EMAIL_REGEX: re.Pattern[str]
INLINE_REFERENCE_REGEX: re.Pattern[str]

Types

from typing import Union, List, Set, Optional, Dict, Tuple
from collections import OrderedDict
from pathlib import Path
from mkdocs.config.defaults import MkDocsConfig
from mkdocs.plugins import BasePlugin
from pybtex.database import BibliographyData
from pybtex.backends.markdown import Backend as MarkdownBackend
from pybtex.style.formatting.plain import Style as PlainStyle