0
# neoteroi-mkdocs
1
2
Plugins for MkDocs and Python Markdown providing OpenAPI documentation, contributor tracking, timelines, cards, advanced tables, and project management features. This comprehensive package extends MkDocs sites with rich visual components and automated documentation capabilities through six distinct plugins and extensions.
3
4
## Package Information
5
6
- **Package Name**: neoteroi-mkdocs
7
- **Package Type**: pypi
8
- **Language**: Python
9
- **Installation**: `pip install neoteroi-mkdocs`
10
- **Python Version**: >=3.7
11
12
## Core Imports
13
14
```python
15
# For MkDocs plugins (configured in mkdocs.yml)
16
# neoteroi.mkdocsoad - OpenAPI documentation plugin
17
# neoteroi.contribs - Contributors plugin
18
19
# For Markdown extensions (configured in mkdocs.yml or used directly)
20
# neoteroi.spantable - Tables with colspan/rowspan
21
# neoteroi.timeline - Timeline visualization
22
# neoteroi.cards - Card layouts
23
# neoteroi.projects - Project management (Gantt charts)
24
```
25
26
## Basic Usage
27
28
### MkDocs Configuration
29
30
Add plugins and extensions to your `mkdocs.yml`:
31
32
```yaml
33
plugins:
34
- neoteroi.mkdocsoad:
35
use_pymdownx: false
36
- neoteroi.contribs:
37
contributors_label: "Contributors"
38
show_last_modified_time: true
39
40
markdown_extensions:
41
- neoteroi.spantable
42
- neoteroi.timeline
43
- neoteroi.cards
44
- neoteroi.projects
45
```
46
47
### Markdown Usage Examples
48
49
```markdown
50
<!-- OpenAPI Documentation -->
51
[OAD(./openapi.yaml)]
52
53
<!-- Timeline -->
54
::timeline::
55
- title: "Project Start"
56
content: "Initial project setup"
57
icon: "play"
58
- title: "Development"
59
content: "Core feature implementation"
60
icon: "code"
61
::end-timeline::
62
63
<!-- Cards -->
64
::cards::
65
- title: "Feature A"
66
content: "Description of feature A"
67
url: "/features/a"
68
- title: "Feature B"
69
content: "Description of feature B"
70
url: "/features/b"
71
::end-cards::
72
73
<!-- Span Table -->
74
::spantable::
75
| Header 1 | Header 2 | Header 3 |
76
|----------|----------|----------|
77
| Cell 1 | Cell 2 spanning 2 cols ||
78
| Cell 3 | Cell 4 | Cell 5 |
79
::end-spantable::
80
81
<!-- Gantt Chart -->
82
::gantt::
83
title: "Project Timeline"
84
activities:
85
- title: "Phase 1"
86
start: "2024-01-01"
87
end: "2024-03-31"
88
- title: "Phase 2"
89
start: "2024-04-01"
90
end: "2024-06-30"
91
::end-gantt::
92
```
93
94
## Architecture
95
96
The package is organized into six main components:
97
98
- **MkDocs Plugins**: `mkdocsoad` and `contribs` provide build-time functionality
99
- **Markdown Extensions**: `spantable`, `timeline`, `cards`, and `projects` provide content processing
100
- **Common Infrastructure**: Shared utilities for data parsing, HTML generation, and configuration
101
102
Each component follows a consistent pattern with domain classes for data modeling, HTML builders for rendering, and processors for Markdown integration.
103
104
## Capabilities
105
106
### OpenAPI Documentation Generation
107
108
Automatically generates documentation from OpenAPI specification files with support for both Markdown and MkDocs styles. Processes `[OAD(...)]` tags in Markdown files.
109
110
```python { .api }
111
class MkDocsOpenAPIDocumentationPlugin(BasePlugin):
112
config_scheme = (("use_pymdownx", Type(bool, default=False)),)
113
114
def on_page_markdown(self, markdown, page, *args, **kwargs): ...
115
```
116
117
[OpenAPI Documentation](./openapi-documentation.md)
118
119
### Git-Based Contributors Tracking
120
121
Displays contributors and last modification information for each page based on Git history. Supports contributor configuration, custom formatting, and conditional display.
122
123
```python { .api }
124
class ContribsPlugin(BasePlugin):
125
config_scheme = (
126
("contributors_label", Type(str, default="Contributors")),
127
("last_modified_label", Type(str, default="Last modified on")),
128
("time_format", Type(str, default="%Y-%m-%d %H:%M:%S")),
129
("contributors", Type(list, default=[])),
130
("show_last_modified_time", Type(bool, default=True)),
131
("show_contributors_title", Type(bool, default=False)),
132
("enabled_by_env", Type(str, default="")),
133
("exclude", Type(list, default=[])),
134
)
135
136
def on_page_markdown(self, markdown, *args, **kwargs): ...
137
```
138
139
[Contributors Tracking](./contributors-tracking.md)
140
141
### Timeline Visualization
142
143
Creates chronological displays with icons, titles, and content. Supports both embedded data and external data sources with customizable styling and layout options.
144
145
```python { .api }
146
class TimelineExtension(Extension):
147
config = {"priority": [12, "The priority to be configured for the extension."]}
148
149
def extendMarkdown(self, md): ...
150
151
class TimelineItem:
152
title: str
153
content: Optional[str]
154
sub_title: Optional[str]
155
icon: Optional[str]
156
key: Optional[str]
157
```
158
159
[Timeline Visualization](./timeline-visualization.md)
160
161
### Card Layouts
162
163
Displays content in card-based grid layouts with support for images, icons, links, and responsive columns. Handles both embedded and external data sources.
164
165
```python { .api }
166
class CardsExtension(Extension):
167
config = {
168
"priority": [12, "The priority to be configured for the extension."],
169
"blank_target": [False, 'Whether to generate links with target="_blank"'],
170
}
171
172
def extendMarkdown(self, md): ...
173
174
class CardItem:
175
title: str
176
url: Optional[str]
177
content: Optional[str]
178
icon: Optional[str]
179
key: Optional[str]
180
image: Optional[Image]
181
```
182
183
[Card Layouts](./card-layouts.md)
184
185
### Advanced Tables
186
187
Tables with colspan and rowspan support using standard Markdown table syntax with cell-spanning notation. Processes `::spantable::` blocks.
188
189
```python { .api }
190
class SpanTableExtension(Extension):
191
def extendMarkdown(self, md): ...
192
193
class Cell:
194
text: str
195
skip: bool
196
col_span: int
197
row_span: int
198
col_span_defined: bool
199
row_span_defined: bool
200
html_class: str
201
```
202
203
[Advanced Tables](./advanced-tables.md)
204
205
### Project Management
206
207
Gantt chart visualization for project planning and timeline management. Supports activities, sub-activities, events, and flexible time scales.
208
209
```python { .api }
210
class ProjectsExtension(Extension):
211
config = {"priority": [12, "The priority to be configured for the extension."]}
212
213
def extendMarkdown(self, md): ...
214
215
class Activity:
216
title: str
217
start: Optional[date]
218
end: Optional[date]
219
description: Optional[str]
220
activities: Optional[List[Activity]]
221
events: Optional[List[Event]]
222
223
def get_overall_start(self) -> Optional[date]: ...
224
def get_overall_end(self) -> Optional[date]: ...
225
226
class Plan(Activity):
227
@classmethod
228
def from_obj(cls, obj): ...
229
```
230
231
[Project Management](./project-management.md)
232
233
## Types
234
235
### Common Types
236
237
```python { .api }
238
class Image:
239
url: str
240
height: Optional[int]
241
width: Optional[int]
242
alt: Optional[str]
243
244
@classmethod
245
def from_obj(cls, obj): ...
246
247
def get_props(self) -> dict: ...
248
249
class Alignment(Enum):
250
CENTER: str
251
LEFT: str
252
RIGHT: str
253
254
class Contributor:
255
name: str
256
email: str
257
count: int
258
image: Optional[str]
259
key: Optional[str]
260
```
261
262
### Data Infrastructure
263
264
```python { .api }
265
class DataReader(ABC):
266
@abstractmethod
267
def test(self, source: str) -> bool: ...
268
269
@abstractmethod
270
def read(self, source: str): ...
271
272
class FileReader(DataReader):
273
def test(self, source: str) -> bool: ...
274
def read(self, source: str): ...
275
276
class HTTPDataReader(DataReader):
277
def test(self, source: str) -> bool: ...
278
def read(self, source: str): ...
279
def get(self, url: str): ...
280
281
class YAMLParser(TextParser):
282
def parse(self, text: str): ...
283
284
class JSONParser(TextParser):
285
def parse(self, text: str): ...
286
287
class CSVParser(TextParser):
288
def parse(self, text: str): ...
289
```