0
# Contributors Tracking
1

2
Displays contributors and last modification information for each page based on Git history. This MkDocs plugin automatically appends contributor statistics to pages, supporting custom contributor configuration, flexible formatting, and conditional display based on environment variables.
3

4
## Capabilities
5

6
### Plugin Configuration
7

8
Configure the contributors plugin with extensive customization options.
9

10
```python { .api }
11
class ContribsPlugin(BasePlugin):
12
    """
13
    MkDocs plugin for displaying contributors and last modification time.
14
    
15
    Configuration options:
16
    - contributors_label: Label for contributors section
17
    - last_modified_label: Label for last modified section  
18
    - time_format: strftime format for dates
19
    - contributors: List of contributor configurations
20
    - show_last_modified_time: Whether to show modification time
21
    - show_contributors_title: Whether to show contributors title
22
    - enabled_by_env: Environment variable to control plugin
23
    - exclude: File patterns to exclude from processing
24
    """
25
    config_scheme = (
26
        ("contributors_label", Type(str, default="Contributors")),
27
        ("last_modified_label", Type(str, default="Last modified on")),
28
        ("time_format", Type(str, default="%Y-%m-%d %H:%M:%S")),
29
        ("contributors", Type(list, default=[])),
30
        ("show_last_modified_time", Type(bool, default=True)),
31
        ("show_contributors_title", Type(bool, default=False)),
32
        ("enabled_by_env", Type(str, default="")),
33
        ("exclude", Type(list, default=[])),
34
    )
35
```
36

37
### Markdown Processing
38

39
The plugin processes pages during the build to append contributor information.
40

41
```python { .api }
42
def on_page_markdown(self, markdown, *args, **kwargs):
43
    """
44
    Appends contributor information to page content.
45
    
46
    Parameters:
47
    - markdown (str): The Markdown content of the page
48
    - kwargs: Contains page object and other context
49
    
50
    Returns:
51
    str: Modified Markdown with contributor information appended
52
    """
53
```
54

55
### Contributor Data Management
56

57
The plugin manages contributor information from multiple sources.
58

59
```python { .api }
60
def _get_contributors(self, page_file) -> List[Contributor]:
61
    """
62
    Retrieves contributor list for a specific file.
63
    
64
    Parameters:
65
    - page_file (File): MkDocs file object
66
    
67
    Returns:
68
    List[Contributor]: List of contributors with commit counts
69
    """
70

71
def _get_last_commit_date(self, page_file) -> datetime:
72
    """
73
    Gets the last commit date for a specific file.
74
    
75
    Parameters:
76
    - page_file (File): MkDocs file object
77
    
78
    Returns:
79
    datetime: Last modification timestamp
80
    """
81
```
82

83
### Contributor Filtering and Merging
84

85
Advanced contributor management with filtering and merging capabilities.
86

87
```python { .api }
88
def _merge_contributor_by_email(
89
    self, contributors: List[Contributor], 
90
    contributor: Contributor, 
91
    contributor_info: dict
92
) -> bool:
93
    """
94
    Handles contributor merging based on configuration.
95
    
96
    Parameters:
97
    - contributors: List of all contributors
98
    - contributor: Current contributor to potentially merge
99
    - contributor_info: Configuration for this contributor
100
    
101
    Returns:
102
    bool: True if contributor was merged and should be skipped
103
    """
104

105
def _is_ignored_page(self, page) -> bool:
106
    """
107
    Checks if a page should be excluded from contributor tracking.
108
    
109
    Parameters:
110
    - page (Page): MkDocs page object
111
    
112
    Returns:
113
    bool: True if page matches exclusion patterns
114
    """
115
```
116

117
## Data Models
118

119
### Contributor Data
120

121
```python { .api }
122
class Contributor:
123
    """
124
    Represents a contributor with commit information.
125
    
126
    Attributes:
127
    - name: Contributor's display name
128
    - email: Contributor's email address
129
    - count: Number of commits
130
    - image: Optional avatar image URL
131
    - key: Optional unique identifier
132
    """
133
    name: str
134
    email: str
135
    count: int
136
    image: Optional[str]
137
    key: Optional[str]
138
```
139

140
### Contribution Readers
141

142
```python { .api }
143
class ContributionsReader(ABC):
144
    """
145
    Abstract base class for reading contribution data.
146
    """
147
    @abstractmethod
148
    def get_contributors(self, file_path: Path) -> List[Contributor]:
149
        """Returns list of contributors for a file."""
150
    
151
    @abstractmethod
152
    def get_last_modified_date(self, file_path: Path) -> datetime:
153
        """Returns last modification date for a file."""
154

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

162
class GitContributionsReader(ContributionsReader):
163
    """
164
    Reads contributor information from Git history.
165
    """
166
    def get_contributors(self, file_path: Path) -> List[Contributor]: ...
167
    def get_last_modified_date(self, file_path: Path) -> datetime: ...
168
    def parse_committers(self, output: str) -> List[Contributor]: ...
169

170
class TXTContributionsReader(ContributionsReader):
171
    """
172
    Reads contributor information from .contributors text files.
173
    """
174
    def get_contributors(self, file_path: Path) -> List[Contributor]: ...
175
    def get_last_modified_date(self, file_path: Path) -> datetime: ...
176
```
177

178
### HTML Rendering
179

180
```python { .api }
181
class ContribsViewOptions:
182
    """
183
    Configuration for rendering contributor information.
184
    
185
    Attributes:
186
    - contributors_label: Label for contributors section
187
    - last_modified_label: Label for last modified section
188
    - show_last_modified_time: Whether to show modification time
189
    - show_contributors_title: Whether to show contributors title
190
    - time_format: strftime format for dates
191
    """
192
    contributors_label: str
193
    last_modified_label: str
194
    show_last_modified_time: bool
195
    show_contributors_title: bool
196
    time_format: str
197

198
def render_contribution_stats(
199
    contributors: List[Contributor], 
200
    last_commit_date: datetime, 
201
    options: ContribsViewOptions
202
) -> str:
203
    """
204
    Renders contributor information as HTML string.
205
    
206
    Parameters:
207
    - contributors: List of contributors
208
    - last_commit_date: Last modification date
209
    - options: Rendering configuration
210
    
211
    Returns:
212
    str: HTML string for contributor information
213
    """
214

215
def contribution_stats_to_element(
216
    contributors: List[Contributor], 
217
    last_commit_date: datetime, 
218
    options: ContribsViewOptions
219
):
220
    """
221
    Creates XML element for contributor information.
222
    
223
    Parameters:
224
    - contributors: List of contributors  
225
    - last_commit_date: Last modification date
226
    - options: Rendering configuration
227
    
228
    Returns:
229
    Element: XML element containing contributor HTML
230
    """
231
```
232

233
## Usage Examples
234

235
### Basic Configuration
236

237
```yaml
238
plugins:
239
  - neoteroi.contribs
240
```
241

242
### Advanced Configuration
243

244
```yaml
245
plugins:
246
  - neoteroi.contribs:
247
      contributors_label: "Authors"
248
      last_modified_label: "Updated"
249
      time_format: "%B %d, %Y"
250
      show_contributors_title: true
251
      exclude:
252
        - "index.md"
253
        - "generated/*"
254
```
255

256
### Contributor Configuration
257

258
```yaml
259
plugins:
260
  - neoteroi.contribs:
261
      contributors:
262
        - email: "john@example.com"
263
          name: "John Smith"
264
          image: "https://github.com/johnsmith.png"
265
        - email: "bot@example.com"
266
          ignore: true
267
        - email: "jane@old-email.com"
268
          merge_with: "jane@new-email.com"
269
```
270

271
### Environment-Based Control
272

273
```yaml
274
plugins:
275
  - neoteroi.contribs:
276
      enabled_by_env: "SHOW_CONTRIBUTORS"
277
```
278

279
Then set environment variable:
280
```bash
281
export SHOW_CONTRIBUTORS=true
282
mkdocs build
283
```
284

285
### Text File Contributors
286

287
Create `.contributors` files alongside Markdown files:
288

289
```
290
docs/
291
├── guide.md
292
├── .contributors  # Contributors for guide.md
293
└── api/
294
    ├── reference.md
295
    └── .contributors  # Contributors for reference.md
296
```
297

298
Format of `.contributors` file:
299
```
300
John Smith <john@example.com>
301
Jane Doe <jane@example.com>
302
```