CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-pymdown-extensions

Extension pack for Python Markdown that provides 20+ specialized extensions for enhanced text processing.

—

Pending
Overview
Eval results
Files

utilities-specialized.mddocs/

Utilities and Specialized Extensions

Utility extensions, content processing tools, and specialized functionality including snippet inclusion, HTML processing, escape handling, tracked changes, enhanced markdown extra, and development utilities.

Capabilities

Snippets (File Inclusion)

Include external file content and code snippets with support for URL fetching, content filtering, and nested inclusions.

def makeExtension(**kwargs):
    """
    Create Snippets extension for external content inclusion.
    
    Configuration:
    - base_path: str - Base path for relative file resolution
    - encoding: str - File encoding ('utf-8')
    - check_paths: bool - Validate file paths (False)
    - auto_append: list - Automatically append file extensions
    - url_timeout: float - URL fetch timeout in seconds (10.0)
    - url_max_size: int - Maximum URL content size (1MB)
    - url_request_headers: dict - Custom HTTP headers
    
    Returns:
    SnippetsExtension instance
    """

class SnippetsExtension(Extension):
    """External content inclusion extension."""

class SnippetsPreprocessor(Preprocessor):
    """Snippet inclusion preprocessor."""

Usage Example:

import markdown

md = markdown.Markdown(extensions=[
    'pymdownx.snippets'
], extension_configs={
    'pymdownx.snippets': {
        'base_path': './docs',
        'check_paths': True,
        'auto_append': ['.md', '.txt']
    }
})

text = '''
# Documentation

--8<-- "common/header.md"

## Code Example

--8<-- "examples/hello.py"

## From URL

--8<-- "https://example.com/snippet.txt"
'''
html = md.convert(text)

StripHTML (HTML Processing)

Remove or escape HTML tags from markdown content with configurable tag handling and content preservation.

def makeExtension(**kwargs):
    """
    Create StripHTML extension for HTML tag processing.
    
    Configuration:
    - strip_comments: bool - Remove HTML comments (True)
    - strip_js_on_attributes: bool - Remove JavaScript event attributes (True)
    - strip_attributes: list - Attributes to remove from all tags
    - strip_js_on_attributes: bool - Remove JavaScript event handlers (True)
    
    Returns:
    StripHtmlExtension instance
    """

class StripHtmlExtension(Extension):
    """HTML stripping and processing extension."""

class StripHtmlPostprocessor(Postprocessor):
    """HTML processing postprocessor."""

Usage Example:

import markdown

md = markdown.Markdown(extensions=[
    'pymdownx.striphtml'
], extension_configs={
    'pymdownx.striphtml': {
        'strip_comments': True,
        'strip_js_on_attributes': True,
        'strip_attributes': ['onclick', 'onload']
    }
})

text = '''
<div onclick="alert('xss')">Safe content</div>
<!-- This comment will be removed -->
<p>Regular paragraph</p>
'''
html = md.convert(text)  # JavaScript and comments removed

EscapeAll (Universal Escaping)

Escape any character with backslash, providing universal escape functionality beyond standard markdown escaping.

def makeExtension(**kwargs):
    """
    Create EscapeAll extension for universal character escaping.
    
    Configuration:
    - hardbreak: bool - Treat escaped newlines as hard breaks (False)
    - nbsp: bool - Treat escaped spaces as non-breaking spaces (False)
    
    Returns:
    EscapeAllExtension instance
    """

class EscapeAllExtension(Extension):
    """Universal character escaping extension."""

class EscapeAllPattern(InlineProcessor):
    """Escape pattern processor."""

Usage Example:

import markdown

md = markdown.Markdown(extensions=['pymdownx.escapeall'])

text = r'''
Escaped \* asterisk doesn't create emphasis.
Escaped \# hash doesn't create header.
Escaped \[ bracket doesn't start link.
Escaped \\ backslash shows literal backslash.
'''
html = md.convert(text)

Critic (CriticMarkup)

CriticMarkup support for tracked changes, comments, and collaborative editing with acceptance/rejection modes.

def makeExtension(**kwargs):
    """
    Create Critic extension for CriticMarkup support.
    
    Configuration:
    - mode: str - Processing mode ('view', 'accept', 'reject')
    
    Returns:
    CriticExtension instance
    """

class CriticExtension(Extension):
    """CriticMarkup tracked changes extension."""

class CriticViewPreprocessor(Preprocessor):
    """Critic marks preprocessor for view mode."""

class CriticsPostprocessor(Postprocessor):
    """Critic output postprocessor."""

class CriticStash:
    """Critic marks stash manager."""

Usage Example:

import markdown

# View mode (default) - shows all marks
md = markdown.Markdown(extensions=['pymdownx.critic'])

# Accept mode - applies additions, removes deletions
md_accept = markdown.Markdown(extensions=[
    'pymdownx.critic'
], extension_configs={
    'pymdownx.critic': {'mode': 'accept'}
})

# Reject mode - removes additions, keeps deletions  
md_reject = markdown.Markdown(extensions=[
    'pymdownx.critic'
], extension_configs={
    'pymdownx.critic': {'mode': 'reject'}
})

text = '''
{++Addition++} and {--deletion--} marks.

{~~Substitution~>replacement~~} example.

{>>Comment<<} annotation.

{==Highlighting==}{>>comment<<} with comment.
'''
html = md.convert(text)

Extra (Enhanced Markdown Extra)

Enhanced version of Python-Markdown Extra with additional features and improved functionality.

def makeExtension(**kwargs):
    """
    Create Extra extension for enhanced Markdown Extra.
    
    Returns:
    ExtraExtension instance
    """

class ExtraExtension(Extension):
    """Enhanced Markdown Extra extension."""

# Included extensions list
extra_extensions = [
    'markdown.extensions.extra',
    'pymdownx.betterem',
    'pymdownx.superfences',
    # ... additional extensions
]

# Extension configurations
extra_extension_configs = {
    'markdown.extensions.extra': {},
    'pymdownx.betterem': {},
    'pymdownx.superfences': {},
    # ... configuration options
}

Usage Example:

import markdown

# Use PyMdown Extra instead of standard Extra
md = markdown.Markdown(extensions=['pymdownx.extra'])

text = '''
# Enhanced Extra Features

- [x] Task lists
- [ ] Better emphasis
- Code fences with highlighting

```python
def hello():
    print("Enhanced code blocks!")

Better emphasis handling. ''' html = md.convert(text)

### Slugs (Header Slugification)

Advanced header ID generation and slugification with Unicode support and customization options.

```python { .api }
def makeExtension(**kwargs):
    """
    Create Slugs extension for header ID generation.
    
    Configuration:
    - slugify: callable - Custom slugify function
    - case: str - Case handling ('lower', 'upper', 'none')
    
    Returns:
    SlugsExtension instance
    """

class SlugsExtension(Extension):
    """Header slugification extension."""

Usage Example:

import markdown

# Custom slugify function
def custom_slugify(text, separator):
    return text.lower().replace(' ', separator)

md = markdown.Markdown(extensions=[
    'pymdownx.slugs'
], extension_configs={
    'pymdownx.slugs': {
        'slugify': custom_slugify,
        'case': 'lower'
    }
})

text = '''
# Main Header
## Sub Header with Spaces
### Unicode Header 中文
'''
html = md.convert(text)

Utility Functions and Classes

Common Utilities

Shared utilities for extension development and markdown processing.

# From pymdownx.util
class PatternSequenceProcessor(InlineProcessor):
    """
    Base class for complex pattern processing.
    
    Handles sequential pattern matching with configurable behavior.
    """

class PatSeqItem:
    """Pattern sequence item namedtuple."""

def clamp(value, min_val, max_val):
    """
    Clamp value to specified range.
    
    Parameters:
    - value: numeric - Value to clamp
    - min_val: numeric - Minimum value
    - max_val: numeric - Maximum value
    
    Returns:
    numeric - Clamped value
    """

def escape_chars(md, chars):
    """
    Add escape characters to Markdown instance.
    
    Parameters:
    - md: Markdown - Markdown instance
    - chars: str - Characters to escape
    """

def deprecated(message):
    """
    Deprecation decorator for functions.
    
    Parameters:
    - message: str - Deprecation message
    
    Returns:
    Decorator function
    """

def warn_deprecated(message):
    """
    Issue deprecation warning.
    
    Parameters:
    - message: str - Warning message
    """

# Platform detection utilities
def is_win():
    """Check if running on Windows."""

def is_linux():
    """Check if running on Linux."""  

def is_mac():
    """Check if running on macOS."""

# URL and path utilities
def url2path(url):
    """Convert URL to file path."""

def path2url(path):
    """Convert file path to URL."""

def parse_url(url):
    """Parse URL with file detection."""

# Unicode utilities
def get_code_points(text):
    """Get Unicode code points from text."""

def get_ord(char):
    """Get Unicode ordinal value."""

def get_char(code_point):
    """Get character from Unicode code point."""

Advanced Configuration Patterns

Snippet Security Configuration

extension_configs = {
    'pymdownx.snippets': {
        'base_path': './safe_directory',
        'check_paths': True,
        'url_timeout': 5.0,
        'url_max_size': 512000,  # 512KB limit
        'url_request_headers': {
            'User-Agent': 'PyMdown-Extensions/1.0'
        }
    }
}

HTML Sanitization Configuration

extension_configs = {
    'pymdownx.striphtml': {
        'strip_comments': True,
        'strip_js_on_attributes': True,
        'strip_attributes': [
            'onclick', 'onload', 'onerror', 'onmouseover',
            'style'  # Remove inline styles
        ]
    }
}

CriticMarkup Workflow

# Review mode - show all changes
review_md = markdown.Markdown(extensions=[
    'pymdownx.critic'
], extension_configs={
    'pymdownx.critic': {'mode': 'view'}
})

# Accept changes
accept_md = markdown.Markdown(extensions=[
    'pymdownx.critic'  
], extension_configs={
    'pymdownx.critic': {'mode': 'accept'}
})

# Reject changes
reject_md = markdown.Markdown(extensions=[
    'pymdownx.critic'
], extension_configs={
    'pymdownx.critic': {'mode': 'reject'}
})

Database and Constants

Emoji and Key Databases

# From emoji database modules
emoji1_db = {
    'name': 'emoji1',
    'emoji': {...},  # Emoji data dictionary
    'aliases': {...}  # Alias mappings
}

gemoji_db = {
    'name': 'gemoji', 
    'emoji': {...},
    'aliases': {...}
}

twemoji_db = {
    'name': 'twemoji',
    'emoji': {...},
    'aliases': {...}
}

keymap_db = {
    'name': 'keymap',
    'keymap': {...}  # Key mapping data
}

Critic Constants

CRITIC_KEY = "critic"  # Critic stash key
SOH = "\x01"  # Start of heading marker
EOT = "\x04"  # End of transmission marker

Types

from typing import Any, Callable, Dict, List, Optional, Union, Tuple
from markdown import Extension, Preprocessor, Postprocessor, InlineProcessor

# Utility types
DeprecationDecorator = Callable[[Callable], Callable]  # Deprecation decorator
Validator = Callable[[Any], bool]  # Validation function
Slugifier = Callable[[str, str], str]  # Slugify function

# File and URL types
FilePath = str  # File path string
URL = str  # URL string
Encoding = str  # Text encoding
Timeout = float  # Timeout in seconds
MaxSize = int  # Maximum size in bytes
Headers = Dict[str, str]  # HTTP headers

# Content processing types
ContentFilter = Callable[[str], str]  # Content filter function
HTMLProcessor = Callable[[str], str]  # HTML processing function
EscapeHandler = Callable[[str], str]  # Escape handling function

# Critic markup types
CriticMode = str  # Critic processing mode ('view', 'accept', 'reject')
CriticMark = str  # Critic markup string

Install with Tessl CLI

npx tessl i tessl/pypi-pymdown-extensions

docs

advanced-blocks.md

code-and-math.md

content-structure.md

index.md

linking-and-media.md

text-enhancement.md

utilities-specialized.md

tile.json