tessl/pypi-markdown2

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

—

Pending

Overview

Eval results

Files

Text Processing Extras

Name: tessl/pypi-markdown2
Author: tessl

Extensions that modify how text elements are processed, including line break behavior, emphasis handling, typography enhancements, and text formatting options.

Capabilities

Line Break Control

Control how line breaks and newlines are handled in the markdown text.

# breaks extra - configurable line break behavior
extras = {
    "breaks": {
        "on_newline": True,    # Replace single newlines with <br>
        "on_backslash": True   # Replace backslash at end of line with <br>
    }
}

# break-on-newline extra - alias for breaks with on_newline=True
extras = ["break-on-newline"]

Usage Examples:

import markdown2

# Enable line breaks on newlines (GitHub-style)
text = """First line
Second line
Third line"""

html = markdown2.markdown(text, extras=["break-on-newline"])
# Result: <p>First line<br>Second line<br>Third line</p>

# Configure both newline and backslash breaks
html = markdown2.markdown(
    "Line 1\\\nLine 2\nLine 3",
    extras={"breaks": {"on_newline": True, "on_backslash": True}}
)

Emphasis and Bold Processing

Control how emphasis markers (_) are processed in text.

# code-friendly extra - disable _ and __ for em and strong
extras = ["code-friendly"]

# middle-word-em extra - control emphasis in middle of words
extras = {
    "middle-word-em": True   # Allow emphasis in middle of words (default)
    # or False to disable (this_text_here won't become this<em>text</em>here)
}

Usage Examples:

import markdown2

# Code-friendly: disable underscore emphasis
code_text = "function_name and another_function_name"
html = markdown2.markdown(code_text, extras=["code-friendly"])
# Underscores won't be treated as emphasis markers

# Control middle-word emphasis
text = "this_is_emphasized_text"
html = markdown2.markdown(
    text, 
    extras={"middle-word-em": False}
)
# Won't convert to: this<em>is</em>emphasized<em>text

Typography Enhancement

Smart typography replacements for professional document formatting.

# smarty-pants extra - smart quotes and punctuation
extras = ["smarty-pants"]

Usage Examples:

import markdown2

text = '''
"Hello," she said. "How are you?"
He replied, "I'm fine -- thanks for asking..."
The 1990's were great.
'''

html = markdown2.markdown(text, extras=["smarty-pants"])
# Converts:
# " " to curly quotes
# -- to en dash
# --- to em dash  
# ... to ellipsis
# 's to curly apostrophe

Text Formatting Extensions

Additional text formatting options beyond standard markdown.

# strike extra - strikethrough text with double tildes
extras = ["strike"]

# underline extra - underline text support
extras = ["underline"]

Usage Examples:

import markdown2

# Strikethrough text
text = "This is ~~strikethrough~~ text"
html = markdown2.markdown(text, extras=["strike"])
# Result: This is <del>strikethrough</del> text

# Underline text (if supported by implementation)
text = "This is _underlined_ text"
html = markdown2.markdown(text, extras=["underline"])

List Processing

Control how lists are processed and formatted.

# cuddled-lists extra - allow lists cuddled to preceding paragraphs
extras = ["cuddled-lists"]

Usage Examples:

import markdown2

text = """This is a paragraph.
- List item 1
- List item 2
- List item 3"""

# Without cuddled-lists: paragraph and list are separate blocks
html1 = markdown2.markdown(text)

# With cuddled-lists: list can be cuddled to paragraph
html2 = markdown2.markdown(text, extras=["cuddled-lists"])

Configuration Options

Breaks Extra Configuration

The breaks extra accepts a dictionary with the following options:

breaks_config = {
    "on_newline": True,     # Convert single newlines to <br> tags
    "on_backslash": True    # Convert backslash-newline to <br> tags
}

Middle-Word Emphasis Configuration

Control emphasis behavior in the middle of words:

# Allow emphasis in middle of words (default behavior)
extras = {"middle-word-em": True}

# Disable emphasis in middle of words (better for code/technical docs)
extras = {"middle-word-em": False}

Combined Usage Examples

import markdown2

# Combine multiple text processing extras
text = """
"Hello world" -- this is a test.

Some code_with_underscores here.
This is ~~deleted~~ text.

First line
Second line
Third line
"""

html = markdown2.markdown(
    text,
    extras=[
        "smarty-pants",      # Smart quotes and punctuation
        "code-friendly",     # Don't treat underscores as emphasis
        "strike",           # Support strikethrough
        "break-on-newline", # Convert newlines to <br>
        "cuddled-lists"     # Allow cuddled list formatting
    ]
)

# Or with configuration options
html = markdown2.markdown(
    text,
    extras={
        "smarty-pants": None,
        "code-friendly": None,
        "strike": None,
        "breaks": {"on_newline": True, "on_backslash": True},
        "middle-word-em": False
    }
)

File Variable Processing

Automatic detection and processing of Emacs-style file variables for enabling extras.

# use-file-vars extra - look for Emacs-style file variables
extras = ["use-file-vars"]

Usage Examples:

import markdown2

# Markdown content with Emacs-style variables
content_with_vars = '''<!--
-*- markdown-extras: footnotes,tables,fenced-code-blocks -*-
-->

# Document Title

This document has footnotes[^1] and tables.

| Col1 | Col2 |
|------|------|
| Data | More |

[^1]: This is a footnote enabled by file variables.
'''

# File variables are automatically detected and applied
html = markdown2.markdown(content_with_vars, use_file_vars=True)
# Equivalent to: extras=["footnotes", "tables", "fenced-code-blocks"]

Compatibility Notes

code-friendly: Particularly useful for technical documentation where underscores are common in code
break-on-newline: Mimics GitHub-flavored markdown line break behavior
smarty-pants: Based on the original SmartyPants by John Gruber
cuddled-lists: Allows more flexible list formatting similar to some other markdown processors