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
```