tessl/pypi-neoteroi-mkdocs

Plugins for MkDocs and Python Markdown providing OpenAPI documentation, contributor tracking, timelines, cards, advanced tables, and project management features.

—

Pending

Overview

Eval results

Files

Timeline Visualization

Name: tessl/pypi-neoteroi-mkdocs
Author: tessl

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.

Capabilities

Extension Configuration

Configure the timeline extension with priority and processing options.

class TimelineExtension(Extension):
    """
    Markdown extension for timeline visualization.
    
    Configuration:
    - priority: Extension processing priority (default: 12)
    """
    config = {"priority": [12, "The priority to be configured for the extension."]}
    
    def extendMarkdown(self, md): ...

Timeline Processing

The extension supports two processing modes for different data sources.

class TimelineEmbeddedProcessor(BaseTimelineProcessor, EmbeddedBlockProcessor):
    """
    Block processor for embedded timeline data using ::timeline:: syntax.
    """

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

class BaseTimelineProcessor:
    """
    Base class for timeline processors with common functionality.
    """
    @property
    def name(self) -> str:
        """Returns 'timeline' as the processor name."""
    
    def build_html(self, parent, obj, props) -> None:
        """
        Builds HTML for timeline components.
        
        Parameters:
        - parent: Parent XML element
        - obj: List of timeline items
        - props: Configuration properties
        """

Data Models

Timeline Data Structures

class TimelineItem:
    """
    Represents a single timeline item.
    
    Attributes:
    - title: Item title (required)
    - content: Item content description
    - sub_title: Optional subtitle
    - icon: Icon identifier (FontAwesome, image, or text)
    - key: Optional unique identifier
    """
    title: str
    content: Optional[str]
    sub_title: Optional[str]
    icon: Optional[str]
    key: Optional[str]

class Timeline:
    """
    Represents a complete timeline with multiple items.
    
    Attributes:
    - items: List of timeline items
    """
    items: List[TimelineItem]

HTML Rendering

class TimelineViewOptions:
    """
    Configuration options for timeline rendering.
    
    Attributes:
    - id: HTML ID attribute
    - class_name: CSS class name
    - alternate: Whether to alternate item positioning
    - align: Timeline alignment (CENTER, LEFT, RIGHT)
    - headings: Whether to render item titles as headings
    """
    id: Optional[str]
    class_name: Optional[str]
    alternate: bool
    align: Alignment
    headings: bool

class TimelineHTMLBuilder:
    """
    Builds HTML for timeline components.
    """
    def build_html(self, parent, timeline: Timeline) -> None:
        """
        Builds complete timeline HTML structure.
        
        Parameters:
        - parent: Parent XML element
        - timeline: Timeline data to render
        """
    
    def build_item_html(self, parent, item: TimelineItem) -> None:
        """
        Builds HTML for individual timeline item.
        
        Parameters:
        - parent: Parent XML element
        - item: Timeline item to render
        """
    
    def get_class(self) -> str:
        """
        Gets CSS classes for timeline container.
        
        Returns:
        str: Space-separated CSS class names
        """

Usage Examples

Embedded Timeline Data

Use ::timeline:: blocks with YAML data:

::timeline::
- title: "Project Kickoff"
  content: "Initial project planning and team setup"
  icon: "play"
  
- title: "Requirements Gathering"
  content: "Stakeholder interviews and documentation"
  sub_title: "Week 1-2"
  icon: "clipboard-list"
  
- title: "Development Phase"
  content: "Core feature implementation and testing"
  sub_title: "Week 3-8"
  icon: "code"
  
- title: "Deployment"
  content: "Production deployment and monitoring setup"
  icon: "rocket"
::end-timeline::

External Timeline Data

Reference external data sources:

[timeline(data.yaml)]

Where data.yaml contains:

- title: "Version 1.0"
  content: "Initial release"
  icon: "tag"
- title: "Version 1.1"
  content: "Bug fixes and improvements"
  icon: "bug"

Timeline with Custom Styling

::timeline:: class="custom-timeline" alternate=true align=center
- title: "Phase One"
  content: "Planning and design"
- title: "Phase Two"
  content: "Implementation"
::end-timeline::

Timeline with Various Icon Types

::timeline::
- title: "FontAwesome Icon"
  content: "Using FontAwesome icon"
  icon: "fas fa-star"
  
- title: "Image Icon"
  content: "Using custom image"
  icon: "./images/milestone.png"
  
- title: "Text Icon"
  content: "Using text as icon"
  icon: "🎯"
  
- title: "No Icon"
  content: "Timeline item without icon"
::end-timeline::

Complex Timeline Example

::timeline:: id="project-timeline" class="major-milestones" headings=true
- title: "Discovery Phase"
  sub_title: "January 2024"
  content: |
    Market research and competitive analysis.
    
    Key deliverables:
    - Market analysis report
    - Competitive landscape study
    - User persona development
  icon: "search"
  
- title: "Design Phase"
  sub_title: "February - March 2024"
  content: |
    User experience design and prototyping.
    
    Activities:
    - Wireframing
    - UI design
    - Prototype development
    - User testing
  icon: "palette"
  
- title: "Development"
  sub_title: "April - August 2024"
  content: "Full-stack development and integration testing"
  icon: "code"
  
- title: "Launch"
  sub_title: "September 2024"
  content: "Production deployment and go-to-market activities"
  icon: "rocket"
::end-timeline::

Data Source Support

Supported Formats

The timeline extension supports multiple data formats:

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

External Data Sources

<!-- Local files -->
[timeline(./data/timeline.yaml)]
[timeline(../shared/milestones.json)]

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

CSV Format Example

title,content,sub_title,icon
"Project Start","Initial setup","Q1 2024","play"
"Development","Core features","Q2 2024","code"
"Launch","Go live","Q3 2024","rocket"

Styling and Customization

CSS Classes

The timeline extension generates semantic HTML with CSS classes:

<div class="timeline">
  <div class="timeline-item">
    <div class="timeline-marker">
      <i class="timeline-icon fas fa-play"></i>
    </div>
    <div class="timeline-content">
      <h3 class="timeline-title">Project Start</h3>
      <p class="timeline-description">Initial setup</p>
    </div>
  </div>
</div>