or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

advanced-tables.mdcard-layouts.mdcontributors-tracking.mdindex.mdopenapi-documentation.mdproject-management.mdtimeline-visualization.md
tile.json

tessl/pypi-neoteroi-mkdocs

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

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/neoteroi-mkdocs@1.1.x

To install, run

npx @tessl/cli install tessl/pypi-neoteroi-mkdocs@1.1.0

index.mddocs/

neoteroi-mkdocs

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.

Package Information

  • Package Name: neoteroi-mkdocs
  • Package Type: pypi
  • Language: Python
  • Installation: pip install neoteroi-mkdocs
  • Python Version: >=3.7

Core Imports

# For MkDocs plugins (configured in mkdocs.yml)
# neoteroi.mkdocsoad - OpenAPI documentation plugin
# neoteroi.contribs - Contributors plugin

# For Markdown extensions (configured in mkdocs.yml or used directly)
# neoteroi.spantable - Tables with colspan/rowspan
# neoteroi.timeline - Timeline visualization
# neoteroi.cards - Card layouts
# neoteroi.projects - Project management (Gantt charts)

Basic Usage

MkDocs Configuration

Add plugins and extensions to your mkdocs.yml:

plugins:
  - neoteroi.mkdocsoad:
      use_pymdownx: false
  - neoteroi.contribs:
      contributors_label: "Contributors"
      show_last_modified_time: true

markdown_extensions:
  - neoteroi.spantable
  - neoteroi.timeline
  - neoteroi.cards
  - neoteroi.projects

Markdown Usage Examples

<!-- OpenAPI Documentation -->
[OAD(./openapi.yaml)]

<!-- Timeline -->
::timeline::
- title: "Project Start"
  content: "Initial project setup"
  icon: "play"
- title: "Development"
  content: "Core feature implementation"
  icon: "code"
::end-timeline::

<!-- Cards -->
::cards::
- title: "Feature A"
  content: "Description of feature A"
  url: "/features/a"
- title: "Feature B"
  content: "Description of feature B"
  url: "/features/b"
::end-cards::

<!-- Span Table -->
::spantable::
| Header 1 | Header 2 | Header 3 |
|----------|----------|----------|
| Cell 1   | Cell 2 spanning 2 cols ||
| Cell 3   | Cell 4   | Cell 5   |
::end-spantable::

<!-- Gantt Chart -->
::gantt::
title: "Project Timeline"
activities:
  - title: "Phase 1"
    start: "2024-01-01"
    end: "2024-03-31"
  - title: "Phase 2"
    start: "2024-04-01"
    end: "2024-06-30"
::end-gantt::

Architecture

The package is organized into six main components:

  • MkDocs Plugins: mkdocsoad and contribs provide build-time functionality
  • Markdown Extensions: spantable, timeline, cards, and projects provide content processing
  • Common Infrastructure: Shared utilities for data parsing, HTML generation, and configuration

Each component follows a consistent pattern with domain classes for data modeling, HTML builders for rendering, and processors for Markdown integration.

Capabilities

OpenAPI Documentation Generation

Automatically generates documentation from OpenAPI specification files with support for both Markdown and MkDocs styles. Processes [OAD(...)] tags in Markdown files.

class MkDocsOpenAPIDocumentationPlugin(BasePlugin):
    config_scheme = (("use_pymdownx", Type(bool, default=False)),)
    
    def on_page_markdown(self, markdown, page, *args, **kwargs): ...

OpenAPI Documentation

Git-Based Contributors Tracking

Displays contributors and last modification information for each page based on Git history. Supports contributor configuration, custom formatting, and conditional display.

class ContribsPlugin(BasePlugin):
    config_scheme = (
        ("contributors_label", Type(str, default="Contributors")),
        ("last_modified_label", Type(str, default="Last modified on")),
        ("time_format", Type(str, default="%Y-%m-%d %H:%M:%S")),
        ("contributors", Type(list, default=[])),
        ("show_last_modified_time", Type(bool, default=True)),
        ("show_contributors_title", Type(bool, default=False)),
        ("enabled_by_env", Type(str, default="")),
        ("exclude", Type(list, default=[])),
    )
    
    def on_page_markdown(self, markdown, *args, **kwargs): ...

Contributors Tracking

Timeline Visualization

Creates chronological displays with icons, titles, and content. Supports both embedded data and external data sources with customizable styling and layout options.

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

class TimelineItem:
    title: str
    content: Optional[str]
    sub_title: Optional[str]
    icon: Optional[str]
    key: Optional[str]

Timeline Visualization

Card Layouts

Displays content in card-based grid layouts with support for images, icons, links, and responsive columns. Handles both embedded and external data sources.

class CardsExtension(Extension):
    config = {
        "priority": [12, "The priority to be configured for the extension."],
        "blank_target": [False, 'Whether to generate links with target="_blank"'],
    }
    
    def extendMarkdown(self, md): ...

class CardItem:
    title: str
    url: Optional[str]
    content: Optional[str]
    icon: Optional[str]
    key: Optional[str]
    image: Optional[Image]

Card Layouts

Advanced Tables

Tables with colspan and rowspan support using standard Markdown table syntax with cell-spanning notation. Processes ::spantable:: blocks.

class SpanTableExtension(Extension):
    def extendMarkdown(self, md): ...

class Cell:
    text: str
    skip: bool
    col_span: int
    row_span: int
    col_span_defined: bool
    row_span_defined: bool
    html_class: str

Advanced Tables

Project Management

Gantt chart visualization for project planning and timeline management. Supports activities, sub-activities, events, and flexible time scales.

class ProjectsExtension(Extension):
    config = {"priority": [12, "The priority to be configured for the extension."]}
    
    def extendMarkdown(self, md): ...

class Activity:
    title: str
    start: Optional[date]
    end: Optional[date]
    description: Optional[str]
    activities: Optional[List[Activity]]
    events: Optional[List[Event]]
    
    def get_overall_start(self) -> Optional[date]: ...
    def get_overall_end(self) -> Optional[date]: ...

class Plan(Activity):
    @classmethod
    def from_obj(cls, obj): ...

Project Management

Types

Common Types

class Image:
    url: str
    height: Optional[int]
    width: Optional[int]
    alt: Optional[str]
    
    @classmethod
    def from_obj(cls, obj): ...
    
    def get_props(self) -> dict: ...

class Alignment(Enum):
    CENTER: str
    LEFT: str
    RIGHT: str

class Contributor:
    name: str
    email: str
    count: int
    image: Optional[str]
    key: Optional[str]

Data Infrastructure

class DataReader(ABC):
    @abstractmethod
    def test(self, source: str) -> bool: ...
    
    @abstractmethod
    def read(self, source: str): ...

class FileReader(DataReader):
    def test(self, source: str) -> bool: ...
    def read(self, source: str): ...

class HTTPDataReader(DataReader):
    def test(self, source: str) -> bool: ...
    def read(self, source: str): ...
    def get(self, url: str): ...

class YAMLParser(TextParser):
    def parse(self, text: str): ...

class JSONParser(TextParser):
    def parse(self, text: str): ...

class CSVParser(TextParser):
    def parse(self, text: str): ...