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

linking-and-media.mddocs/

Linking and Media Extensions

Extensions for automatic linking, comprehensive emoji support, keyboard key formatting, and link processing enhancements for creating rich, interactive content.

Capabilities

Emoji Support

Comprehensive emoji support with multiple providers (Twemoji, EmojiOne, Gemoji) and customizable output formats including PNG, SVG, and sprites.

def makeExtension(**kwargs):
    """
    Create Emoji extension with multiple provider support.
    
    Configuration:
    - emoji_index: callable - Emoji index function (twemoji)
    - emoji_generator: callable - Emoji HTML generator (to_svg)
    - options: dict - Provider-specific options
    
    Returns:
    EmojiExtension instance
    """

class EmojiExtension(Extension):
    """Comprehensive emoji support extension."""

class EmojiPattern(InlineProcessor):
    """Emoji pattern processor."""

class EmojiAlertPostprocessor(Postprocessor):
    """Strict mode alert processor."""

# Provider index functions
def emojione(options, md):
    """EmojiOne emoji index provider."""

def gemoji(options, md):
    """GitHub Gemoji emoji index provider."""

def twemoji(options, md):
    """Twitter Twemoji emoji index provider."""

# Output format converters
def to_png(index, shortname, alias, uc, alt, options, **kwargs):
    """Convert emoji to PNG format."""

def to_svg(index, shortname, alias, uc, alt, options, **kwargs):
    """Convert emoji to SVG format."""

def to_png_sprite(index, shortname, alias, uc, alt, options, **kwargs):
    """Convert emoji to PNG sprite format."""

def to_svg_sprite(index, shortname, alias, uc, alt, options, **kwargs):
    """Convert emoji to SVG sprite format."""

def to_alt(index, shortname, alias, uc, alt, options, **kwargs):
    """Convert emoji to alt text format."""

def add_attributes(attrs={}):
    """Add custom attributes to emoji elements."""

# Backward compatibility alias (note: intentionally misspelled in source)
add_attriubtes = add_attributes

Usage Example:

import markdown
from pymdownx import emoji

# Basic emoji support with Twemoji
md = markdown.Markdown(extensions=['pymdownx.emoji'])

# Custom configuration
md = markdown.Markdown(extensions=[
    'pymdownx.emoji'
], extension_configs={
    'pymdownx.emoji': {
        'emoji_index': emoji.gemoji,
        'emoji_generator': emoji.to_png,
        'options': {
            'attributes': {'align': 'absmiddle', 'height': '20px', 'width': '20px'},
            'image_path': 'https://github.githubassets.com/images/icons/emoji/unicode/',
            'non_standard_image_path': 'https://github.githubassets.com/images/icons/emoji/'
        }
    }
})

text = """
I love Python! :snake: :heart: :+1:

GitHub style: :octocat: :shipit:

Unicode: 🐍 ❤️ 👍
"""
html = md.convert(text)

MagicLink (Automatic Linking)

Automatic linking for URLs, email addresses, and repository references with support for GitHub, GitLab, Bitbucket, and custom providers.

def makeExtension(**kwargs):
    """
    Create MagicLink extension for automatic linking.
    
    Configuration:
    - hide_protocol: bool - Hide protocol in displayed URLs (False)
    - repo_url_shortener: bool - Shorten repository URLs (False)
    - social_url_shortener: bool - Shorten social media URLs (False)
    - provider: str - Repository provider ('github')
    - user: str - Default repository user
    - repo: str - Default repository name
    
    Returns:
    MagiclinkExtension instance
    """

class MagiclinkExtension(Extension):
    """Automatic linking extension."""

class MagiclinkPattern(InlineProcessor):
    """Link pattern processor."""

Usage Example:

import markdown

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

text = """
Visit https://www.example.com for more info.

Email me at user@example.com

Repository: facelessuser/pymdown-extensions

Issue: #123
Pull Request: !456
Commit: abc123def
"""
html = md.convert(text)

# With repository context
md = markdown.Markdown(extensions=[
    'pymdownx.magiclink'
], extension_configs={
    'pymdownx.magiclink': {
        'provider': 'github',
        'user': 'facelessuser',
        'repo': 'pymdown-extensions'
    }
})

Keys (Keyboard Key Formatting)

Keyboard key styling and formatting with support for key combinations, modifiers, and custom key mappings.

def makeExtension(**kwargs):
    """
    Create Keys extension for keyboard key formatting.
    
    Configuration:
    - separator: str - Key combination separator ('+')
    - strict: bool - Strict key validation (True)
    - camel_case: bool - Use camelCase for key names (False)
    
    Returns:
    KeysExtension instance
    """

class KeysExtension(Extension):
    """Keyboard key formatting extension."""

class KeysPattern(InlineProcessor):
    """Key pattern processor."""

Usage Example:

import markdown

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

text = """
Press ++ctrl+alt+delete++ to restart.

Use ++cmd+c++ to copy on Mac.

Press ++f1++ for help.

Shortcut: ++ctrl+shift+p++
"""
html = md.convert(text)

PathConverter (Path Processing)

Convert and normalize file paths in links with support for relative path resolution and cross-platform compatibility.

def makeExtension(**kwargs):
    """
    Create PathConverter extension for path processing.
    
    Configuration:
    - base_path: str - Base path for relative resolution
    - relative_path: str - Relative path prefix
    - absolute: bool - Convert to absolute paths (False)
    - tags: str - HTML tags to process ('a img object embed')
    
    Returns:
    PathConverterExtension instance
    """

class PathConverterExtension(Extension):
    """Path conversion and normalization extension."""

class PathConverterTreeprocessor(Treeprocessor):
    """Path conversion processor."""

Usage Example:

import markdown

md = markdown.Markdown(extensions=[
    'pymdownx.pathconverter'
], extension_configs={
    'pymdownx.pathconverter': {
        'base_path': '/docs',
        'relative_path': '../images/',
        'absolute': True
    }
})

text = """
![Image](./image.png)

[Document](../files/doc.pdf)
"""
html = md.convert(text)

Emoji Configuration Patterns

Provider Selection and Configuration

from pymdownx import emoji

# Twemoji configuration
extension_configs = {
    'pymdownx.emoji': {
        'emoji_index': emoji.twemoji,
        'emoji_generator': emoji.to_svg,
        'options': {
            'image_path': 'https://cdn.jsdelivr.net/gh/jdecked/twemoji@15.1.0/assets/svg/',
            'non_standard_image_path': 'https://cdn.jsdelivr.net/gh/jdecked/twemoji@15.1.0/assets/svg/'
        }
    }
}

# GitHub Gemoji configuration
extension_configs = {
    'pymdownx.emoji': {
        'emoji_index': emoji.gemoji,
        'emoji_generator': emoji.to_png,
        'options': {
            'image_path': 'https://github.githubassets.com/images/icons/emoji/unicode/',
            'non_standard_image_path': 'https://github.githubassets.com/images/icons/emoji/'
        }
    }
}

# EmojiOne configuration
extension_configs = {
    'pymdownx.emoji': {
        'emoji_index': emoji.emojione,
        'emoji_generator': emoji.to_svg,
        'options': {
            'image_path': 'https://cdn.jsdelivr.net/emojione/assets/svg/',
            'non_standard_image_path': 'https://cdn.jsdelivr.net/emojione/assets/svg/'
        }
    }
}

Custom Emoji Attributes

from pymdownx.emoji import add_attributes

extension_configs = {
    'pymdownx.emoji': {
        'emoji_generator': add_attributes(
            emoji.to_svg, 
            {'class': 'custom-emoji', 'height': '1em', 'width': '1em'}
        )
    }
}

MagicLink Provider Configuration

GitHub Integration

extension_configs = {
    'pymdownx.magiclink': {
        'provider': 'github',
        'user': 'username',
        'repo': 'repository',
        'repo_url_shortener': True,
        'social_url_shortener': True
    }
}

GitLab Integration

extension_configs = {
    'pymdownx.magiclink': {
        'provider': 'gitlab',
        'user': 'username',
        'repo': 'repository'
    }
}

Bitbucket Integration

extension_configs = {
    'pymdownx.magiclink': {
        'provider': 'bitbucket',
        'user': 'username',
        'repo': 'repository'
    }
}

Advanced Linking Patterns

Repository Reference Patterns

# Issue references: #123
# Pull request references: !456  
# Commit references: abc123def456
# Mention references: @username
# Repository references: user/repo

Custom Key Mappings

extension_configs = {
    'pymdownx.keys': {
        'separator': '-',
        'strict': False,
        'camel_case': True
    }
}

Constants and Databases

# CDN URLs for emoji providers  
EMOJIONE_SVG_CDN = "https://cdn.jsdelivr.net/emojione/assets/svg/"
TWEMOJI_SVG_CDN = "https://cdn.jsdelivr.net/gh/jdecked/twemoji@15.1.0/assets/svg/"
TWEMOJI_PNG_CDN = "https://cdn.jsdelivr.net/gh/jdecked/twemoji@15.1.0/assets/72x72/"
GITHUB_CDN = "https://github.githubassets.com/images/icons/emoji/"

# Supported emoji indexes
SUPPORTED_INDEXES = ['emojione', 'twemoji', 'gemoji']

# Default exclusions for MagicLink providers
DEFAULT_EXCLUDES = {
    'github': [...],
    'gitlab': [...],
    'bitbucket': [...]
}

Types

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

# Emoji-related types
EmojiIndex = Callable[[Dict, Any], Dict]  # Emoji index provider function
EmojiGenerator = Callable[..., str]  # Emoji HTML generator function
EmojiOptions = Dict[str, Any]  # Emoji provider options

# Link-related types
LinkProcessor = Callable[[str], str]  # Custom link processor
PathResolver = Callable[[str, str], str]  # Path resolution function
ProviderConfig = Dict[str, Any]  # Provider configuration

# Key-related types
KeySeparator = str  # Key combination separator
KeyMap = Dict[str, str]  # Custom key mappings

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