0
# Timeline Visualization
1

2
Creates chronological displays with icons, titles, and content. This Markdown extension provides timeline components for displaying chronological information with rich styling, supporting both embedded data and external data sources with customizable layout options.
3

4
## Capabilities
5

6
### Extension Configuration
7

8
Configure the timeline extension with priority and processing options.
9

10
```python { .api }
11
class TimelineExtension(Extension):
12
    """
13
    Markdown extension for timeline visualization.
14
    
15
    Configuration:
16
    - priority: Extension processing priority (default: 12)
17
    """
18
    config = {"priority": [12, "The priority to be configured for the extension."]}
19
    
20
    def extendMarkdown(self, md): ...
21
```
22

23
### Timeline Processing
24

25
The extension supports two processing modes for different data sources.
26

27
```python { .api }
28
class TimelineEmbeddedProcessor(BaseTimelineProcessor, EmbeddedBlockProcessor):
29
    """
30
    Block processor for embedded timeline data using ::timeline:: syntax.
31
    """
32

33
class TimelineSourceProcessor(BaseTimelineProcessor, SourceBlockProcessor):
34
    """
35
    Block processor for external timeline data using [timeline(...)] syntax.
36
    """
37

38
class BaseTimelineProcessor:
39
    """
40
    Base class for timeline processors with common functionality.
41
    """
42
    @property
43
    def name(self) -> str:
44
        """Returns 'timeline' as the processor name."""
45
    
46
    def build_html(self, parent, obj, props) -> None:
47
        """
48
        Builds HTML for timeline components.
49
        
50
        Parameters:
51
        - parent: Parent XML element
52
        - obj: List of timeline items
53
        - props: Configuration properties
54
        """
55
```
56

57
## Data Models
58

59
### Timeline Data Structures
60

61
```python { .api }
62
class TimelineItem:
63
    """
64
    Represents a single timeline item.
65
    
66
    Attributes:
67
    - title: Item title (required)
68
    - content: Item content description
69
    - sub_title: Optional subtitle
70
    - icon: Icon identifier (FontAwesome, image, or text)
71
    - key: Optional unique identifier
72
    """
73
    title: str
74
    content: Optional[str]
75
    sub_title: Optional[str]
76
    icon: Optional[str]
77
    key: Optional[str]
78

79
class Timeline:
80
    """
81
    Represents a complete timeline with multiple items.
82
    
83
    Attributes:
84
    - items: List of timeline items
85
    """
86
    items: List[TimelineItem]
87
```
88

89
### HTML Rendering
90

91
```python { .api }
92
class TimelineViewOptions:
93
    """
94
    Configuration options for timeline rendering.
95
    
96
    Attributes:
97
    - id: HTML ID attribute
98
    - class_name: CSS class name
99
    - alternate: Whether to alternate item positioning
100
    - align: Timeline alignment (CENTER, LEFT, RIGHT)
101
    - headings: Whether to render item titles as headings
102
    """
103
    id: Optional[str]
104
    class_name: Optional[str]
105
    alternate: bool
106
    align: Alignment
107
    headings: bool
108

109
class TimelineHTMLBuilder:
110
    """
111
    Builds HTML for timeline components.
112
    """
113
    def build_html(self, parent, timeline: Timeline) -> None:
114
        """
115
        Builds complete timeline HTML structure.
116
        
117
        Parameters:
118
        - parent: Parent XML element
119
        - timeline: Timeline data to render
120
        """
121
    
122
    def build_item_html(self, parent, item: TimelineItem) -> None:
123
        """
124
        Builds HTML for individual timeline item.
125
        
126
        Parameters:
127
        - parent: Parent XML element
128
        - item: Timeline item to render
129
        """
130
    
131
    def get_class(self) -> str:
132
        """
133
        Gets CSS classes for timeline container.
134
        
135
        Returns:
136
        str: Space-separated CSS class names
137
        """
138
```
139

140
## Usage Examples
141

142
### Embedded Timeline Data
143

144
Use `::timeline::` blocks with YAML data:
145

146
```markdown
147
::timeline::
148
- title: "Project Kickoff"
149
  content: "Initial project planning and team setup"
150
  icon: "play"
151
  
152
- title: "Requirements Gathering"
153
  content: "Stakeholder interviews and documentation"
154
  sub_title: "Week 1-2"
155
  icon: "clipboard-list"
156
  
157
- title: "Development Phase"
158
  content: "Core feature implementation and testing"
159
  sub_title: "Week 3-8"
160
  icon: "code"
161
  
162
- title: "Deployment"
163
  content: "Production deployment and monitoring setup"
164
  icon: "rocket"
165
::end-timeline::
166
```
167

168
### External Timeline Data
169

170
Reference external data sources:
171

172
```markdown
173
[timeline(data.yaml)]
174
```
175

176
Where `data.yaml` contains:
177
```yaml
178
- title: "Version 1.0"
179
  content: "Initial release"
180
  icon: "tag"
181
- title: "Version 1.1"
182
  content: "Bug fixes and improvements"
183
  icon: "bug"
184
```
185

186
### Timeline with Custom Styling
187

188
```markdown
189
::timeline:: class="custom-timeline" alternate=true align=center
190
- title: "Phase One"
191
  content: "Planning and design"
192
- title: "Phase Two"
193
  content: "Implementation"
194
::end-timeline::
195
```
196

197
### Timeline with Various Icon Types
198

199
```markdown
200
::timeline::
201
- title: "FontAwesome Icon"
202
  content: "Using FontAwesome icon"
203
  icon: "fas fa-star"
204
  
205
- title: "Image Icon"
206
  content: "Using custom image"
207
  icon: "./images/milestone.png"
208
  
209
- title: "Text Icon"
210
  content: "Using text as icon"
211
  icon: "🎯"
212
  
213
- title: "No Icon"
214
  content: "Timeline item without icon"
215
::end-timeline::
216
```
217

218
### Complex Timeline Example
219

220
```markdown
221
::timeline:: id="project-timeline" class="major-milestones" headings=true
222
- title: "Discovery Phase"
223
  sub_title: "January 2024"
224
  content: |
225
    Market research and competitive analysis.
226
    
227
    Key deliverables:
228
    - Market analysis report
229
    - Competitive landscape study
230
    - User persona development
231
  icon: "search"
232
  
233
- title: "Design Phase"
234
  sub_title: "February - March 2024"
235
  content: |
236
    User experience design and prototyping.
237
    
238
    Activities:
239
    - Wireframing
240
    - UI design
241
    - Prototype development
242
    - User testing
243
  icon: "palette"
244
  
245
- title: "Development"
246
  sub_title: "April - August 2024"
247
  content: "Full-stack development and integration testing"
248
  icon: "code"
249
  
250
- title: "Launch"
251
  sub_title: "September 2024"
252
  content: "Production deployment and go-to-market activities"
253
  icon: "rocket"
254
::end-timeline::
255
```
256

257
## Data Source Support
258

259
### Supported Formats
260

261
The timeline extension supports multiple data formats:
262

263
- **YAML**: Structured timeline data (recommended)
264
- **JSON**: JavaScript Object Notation format
265
- **CSV**: Comma-separated values with column headers
266

267
### External Data Sources
268

269
```markdown
270
<!-- Local files -->
271
[timeline(./data/timeline.yaml)]
272
[timeline(../shared/milestones.json)]
273

274
<!-- URLs (if configured) -->
275
[timeline(https://api.example.com/timeline.json)]
276
```
277

278
### CSV Format Example
279

280
```csv
281
title,content,sub_title,icon
282
"Project Start","Initial setup","Q1 2024","play"
283
"Development","Core features","Q2 2024","code"
284
"Launch","Go live","Q3 2024","rocket"
285
```
286

287
## Styling and Customization
288

289
### CSS Classes
290

291
The timeline extension generates semantic HTML with CSS classes:
292

293
```html
294
<div class="timeline">
295
  <div class="timeline-item">
296
    <div class="timeline-marker">
297
      <i class="timeline-icon fas fa-play"></i>
298
    </div>
299
    <div class="timeline-content">
300
      <h3 class="timeline-title">Project Start</h3>
301
      <p class="timeline-description">Initial setup</p>
302
    </div>
303
  </div>
304
</div>
305
```
306

307
### Alignment Options
308

309
- `align=left`: Left-aligned timeline
310
- `align=center`: Centered timeline (default)
311
- `align=right`: Right-aligned timeline
312

313
### Alternating Layout
314

315
Use `alternate=true` to create alternating left/right item positioning for better visual flow.