Contributors Tracking

class ContribsPlugin(BasePlugin):
    """
    MkDocs plugin for displaying contributors and last modification time.
    
    Configuration options:
    - contributors_label: Label for contributors section
    - last_modified_label: Label for last modified section  
    - time_format: strftime format for dates
    - contributors: List of contributor configurations
    - show_last_modified_time: Whether to show modification time
    - show_contributors_title: Whether to show contributors title
    - enabled_by_env: Environment variable to control plugin
    - exclude: File patterns to exclude from processing
    """
    config_scheme = (
        ("contributors_label", Type(str, default="Contributors")),
        ("last_modified_label", Type(str, default="Last modified on")),
        ("time_format", Type(str, default="%Y-%m-%d %H:%M:%S")),
        ("contributors", Type(list, default=[])),
        ("show_last_modified_time", Type(bool, default=True)),
        ("show_contributors_title", Type(bool, default=False)),
        ("enabled_by_env", Type(str, default="")),
        ("exclude", Type(list, default=[])),
    )

def on_page_markdown(self, markdown, *args, **kwargs):
    """
    Appends contributor information to page content.
    
    Parameters:
    - markdown (str): The Markdown content of the page
    - kwargs: Contains page object and other context
    
    Returns:
    str: Modified Markdown with contributor information appended
    """

def _get_contributors(self, page_file) -> List[Contributor]:
    """
    Retrieves contributor list for a specific file.
    
    Parameters:
    - page_file (File): MkDocs file object
    
    Returns:
    List[Contributor]: List of contributors with commit counts
    """

def _get_last_commit_date(self, page_file) -> datetime:
    """
    Gets the last commit date for a specific file.
    
    Parameters:
    - page_file (File): MkDocs file object
    
    Returns:
    datetime: Last modification timestamp
    """

def _merge_contributor_by_email(
    self, contributors: List[Contributor], 
    contributor: Contributor, 
    contributor_info: dict
) -> bool:
    """
    Handles contributor merging based on configuration.
    
    Parameters:
    - contributors: List of all contributors
    - contributor: Current contributor to potentially merge
    - contributor_info: Configuration for this contributor
    
    Returns:
    bool: True if contributor was merged and should be skipped
    """

def _is_ignored_page(self, page) -> bool:
    """
    Checks if a page should be excluded from contributor tracking.
    
    Parameters:
    - page (Page): MkDocs page object
    
    Returns:
    bool: True if page matches exclusion patterns
    """

class Contributor:
    """
    Represents a contributor with commit information.
    
    Attributes:
    - name: Contributor's display name
    - email: Contributor's email address
    - count: Number of commits
    - image: Optional avatar image URL
    - key: Optional unique identifier
    """
    name: str
    email: str
    count: int
    image: Optional[str]
    key: Optional[str]

class ContributionsReader(ABC):
    """
    Abstract base class for reading contribution data.
    """
    @abstractmethod
    def get_contributors(self, file_path: Path) -> List[Contributor]:
        """Returns list of contributors for a file."""
    
    @abstractmethod
    def get_last_modified_date(self, file_path: Path) -> datetime:
        """Returns last modification date for a file."""

class DefaultContributionsReader(ContributionsReader):
    """
    Default implementation combining Git and text file sources.
    """
    def get_contributors(self, file_path: Path) -> List[Contributor]: ...
    def get_last_modified_date(self, file_path: Path) -> datetime: ...

class GitContributionsReader(ContributionsReader):
    """
    Reads contributor information from Git history.
    """
    def get_contributors(self, file_path: Path) -> List[Contributor]: ...
    def get_last_modified_date(self, file_path: Path) -> datetime: ...
    def parse_committers(self, output: str) -> List[Contributor]: ...

class TXTContributionsReader(ContributionsReader):
    """
    Reads contributor information from .contributors text files.
    """
    def get_contributors(self, file_path: Path) -> List[Contributor]: ...
    def get_last_modified_date(self, file_path: Path) -> datetime: ...

class ContribsViewOptions:
    """
    Configuration for rendering contributor information.
    
    Attributes:
    - contributors_label: Label for contributors section
    - last_modified_label: Label for last modified section
    - show_last_modified_time: Whether to show modification time
    - show_contributors_title: Whether to show contributors title
    - time_format: strftime format for dates
    """
    contributors_label: str
    last_modified_label: str
    show_last_modified_time: bool
    show_contributors_title: bool
    time_format: str

def render_contribution_stats(
    contributors: List[Contributor], 
    last_commit_date: datetime, 
    options: ContribsViewOptions
) -> str:
    """
    Renders contributor information as HTML string.
    
    Parameters:
    - contributors: List of contributors
    - last_commit_date: Last modification date
    - options: Rendering configuration
    
    Returns:
    str: HTML string for contributor information
    """

def contribution_stats_to_element(
    contributors: List[Contributor], 
    last_commit_date: datetime, 
    options: ContribsViewOptions
):
    """
    Creates XML element for contributor information.
    
    Parameters:
    - contributors: List of contributors  
    - last_commit_date: Last modification date
    - options: Rendering configuration
    
    Returns:
    Element: XML element containing contributor HTML
    """

plugins:
  - neoteroi.contribs

plugins:
  - neoteroi.contribs:
      contributors_label: "Authors"
      last_modified_label: "Updated"
      time_format: "%B %d, %Y"
      show_contributors_title: true
      exclude:
        - "index.md"
        - "generated/*"

plugins:
  - neoteroi.contribs:
      contributors:
        - email: "john@example.com"
          name: "John Smith"
          image: "https://github.com/johnsmith.png"
        - email: "bot@example.com"
          ignore: true
        - email: "jane@old-email.com"
          merge_with: "jane@new-email.com"

plugins:
  - neoteroi.contribs:
      enabled_by_env: "SHOW_CONTRIBUTORS"

export SHOW_CONTRIBUTORS=true
mkdocs build

docs/
├── guide.md
├── .contributors  # Contributors for guide.md
└── api/
    ├── reference.md
    └── .contributors  # Contributors for reference.md

John Smith <john@example.com>
Jane Doe <jane@example.com>