tessl/pypi-markdown2

A fast and complete Python implementation of Markdown with extensive extras support

—

Pending

Overview

Eval results

Files

Core Conversion Functions

Name: tessl/pypi-markdown2
Author: tessl

Essential functions for converting markdown text and files to HTML. These functions provide the primary interface for markdown2's conversion capabilities with extensive configuration options.

Capabilities

Text Conversion

Converts markdown text directly to HTML with full control over processing options and extras.

def markdown(
    text: str,
    html4tags: bool = False,
    tab_width: int = 4,
    safe_mode: Optional[Literal['replace', 'escape']] = None,
    extras: Optional[Union[list[str], dict[str, Any]]] = None,
    link_patterns: Optional[Iterable[tuple[re.Pattern, Union[str, Callable[[re.Match], str]]]]] = None,
    footnote_title: Optional[str] = None,
    footnote_return_symbol: Optional[str] = None,
    use_file_vars: bool = False,
    cli: bool = False
) -> UnicodeWithAttrs:
    """
    Convert markdown text to HTML.

    Parameters:
    - text: Markdown text to convert
    - html4tags: Use HTML 4 style for empty element tags (default: False for XHTML style)
    - tab_width: Number of spaces per tab for code block indentation (default: 4)
    - safe_mode: Sanitize literal HTML ('escape' or 'replace', default: None)
    - extras: List of extra names or dict of extra_name -> extra_arg (default: None)
    - link_patterns: Auto-link regex patterns as (pattern, replacement) tuples (default: None)
    - footnote_title: Title attribute for footnote links (default: None)
    - footnote_return_symbol: Symbol for footnote return links (default: None)
    - use_file_vars: Look for Emacs-style file variables to enable extras (default: False)
    - cli: Enable CLI-specific behavior for command-line usage (default: False)

    Returns:
    UnicodeWithAttrs: HTML string with optional metadata and toc_html attributes
    """

Usage Examples:

import markdown2

# Basic conversion
html = markdown2.markdown("**Hello** *world*!")
# Returns: '<p><strong>Hello</strong> <em>world</em>!</p>\n'

# With extras
html = markdown2.markdown(
    "```python\nprint('hello')\n```",
    extras=["fenced-code-blocks", "code-friendly"]
)

# With safe mode (sanitize HTML)
html = markdown2.markdown(
    "Some text <script>alert('xss')</script>",
    safe_mode="escape"
)

# With custom link patterns
import re
patterns = [(re.compile(r'issue #(\d+)'), r'https://github.com/user/repo/issues/\1')]
html = markdown2.markdown(
    "See issue #123 for details",
    extras={"link-patterns": patterns}
)

File Conversion

Converts markdown files to HTML with automatic file encoding handling.

def markdown_path(
    path: str,
    encoding: str = "utf-8",
    html4tags: bool = False,
    tab_width: int = 4,
    safe_mode: Optional[Literal['replace', 'escape']] = None,
    extras: Optional[Union[list[str], dict[str, Any]]] = None,
    link_patterns: Optional[Iterable[tuple[re.Pattern, Union[str, Callable[[re.Match], str]]]]] = None,
    footnote_title: Optional[str] = None,
    footnote_return_symbol: Optional[str] = None,
    use_file_vars: bool = False
) -> UnicodeWithAttrs:
    """
    Convert markdown file to HTML.

    Parameters:
    - path: Path to markdown file to convert
    - encoding: File encoding to use for reading (default: 'utf-8')
    - (all other parameters same as markdown() function except 'cli')

    Returns:
    UnicodeWithAttrs: HTML string with optional metadata and toc_html attributes
    """

Usage Examples:

import markdown2

# Convert file with default settings
html = markdown2.markdown_path("README.md")

# Convert with specific encoding and extras
html = markdown2.markdown_path(
    "document.md",
    encoding="latin-1",
    extras=["tables", "footnotes", "toc"]
)

# Access table of contents if 'toc' extra is used
if hasattr(html, 'toc_html') and html.toc_html:
    print("Table of Contents:", html.toc_html)

# Access metadata if 'metadata' extra is used
if hasattr(html, 'metadata') and html.metadata:
    print("Title:", html.metadata.get('title'))

Configuration Options

HTML Output Format

html4tags=False: Use XHTML-style empty elements (<br />)
html4tags=True: Use HTML4-style empty elements (<br>)

Tab Handling

tab_width=4: Number of spaces each tab character represents in code blocks

Security Options

safe_mode=None: Allow all HTML tags (default)
safe_mode="escape": Escape HTML characters (< becomes <)
safe_mode="replace": Replace HTML with [HTML_REMOVED] placeholder

Extras Configuration

Extras can be specified as:

List of strings: extras=["tables", "footnotes"]
Dictionary: extras={"tables": None, "header-ids": {"prefix": "section-"}}

Link Pattern Configuration

Auto-linking patterns as tuples of (compiled_regex, replacement):

String replacement: (re.compile(r'#(\d+)'), r'https://github.com/issues/\1')
Callable replacement: (re.compile(r'@(\w+)'), lambda m: f'<a href="/users/{m.group(1)}">@{m.group(1)}</a>')

File Variable Processing

When use_file_vars=True, markdown2 looks for Emacs-style file variables like:

<!-- markdown-extras: footnotes, tables -->

Install with Tessl CLI

npx tessl i tessl/pypi-markdown2

docs

code-syntax-extras.md

core-conversion.md

index.md

link-reference-extras.md

processor-classes.md

special-content-extras.md

structure-layout-extras.md

text-processing-extras.md

tile.json