0
# Core Conversion Functions
1

2
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.
3

4
## Capabilities
5

6
### Text Conversion
7

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

10
```python { .api }
11
def markdown(
12
    text: str,
13
    html4tags: bool = False,
14
    tab_width: int = 4,
15
    safe_mode: Optional[Literal['replace', 'escape']] = None,
16
    extras: Optional[Union[list[str], dict[str, Any]]] = None,
17
    link_patterns: Optional[Iterable[tuple[re.Pattern, Union[str, Callable[[re.Match], str]]]]] = None,
18
    footnote_title: Optional[str] = None,
19
    footnote_return_symbol: Optional[str] = None,
20
    use_file_vars: bool = False,
21
    cli: bool = False
22
) -> UnicodeWithAttrs:
23
    """
24
    Convert markdown text to HTML.
25

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

38
    Returns:
39
    UnicodeWithAttrs: HTML string with optional metadata and toc_html attributes
40
    """
41
```
42

43
**Usage Examples:**
44

45
```python
46
import markdown2
47

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

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

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

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

73
### File Conversion
74

75
Converts markdown files to HTML with automatic file encoding handling.
76

77
```python { .api }
78
def markdown_path(
79
    path: str,
80
    encoding: str = "utf-8",
81
    html4tags: bool = False,
82
    tab_width: int = 4,
83
    safe_mode: Optional[Literal['replace', 'escape']] = None,
84
    extras: Optional[Union[list[str], dict[str, Any]]] = None,
85
    link_patterns: Optional[Iterable[tuple[re.Pattern, Union[str, Callable[[re.Match], str]]]]] = None,
86
    footnote_title: Optional[str] = None,
87
    footnote_return_symbol: Optional[str] = None,
88
    use_file_vars: bool = False
89
) -> UnicodeWithAttrs:
90
    """
91
    Convert markdown file to HTML.
92

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

98
    Returns:
99
    UnicodeWithAttrs: HTML string with optional metadata and toc_html attributes
100
    """
101
```
102

103
**Usage Examples:**
104

105
```python
106
import markdown2
107

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

111
# Convert with specific encoding and extras
112
html = markdown2.markdown_path(
113
    "document.md",
114
    encoding="latin-1",
115
    extras=["tables", "footnotes", "toc"]
116
)
117

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

122
# Access metadata if 'metadata' extra is used
123
if hasattr(html, 'metadata') and html.metadata:
124
    print("Title:", html.metadata.get('title'))
125
```
126

127
## Configuration Options
128

129
### HTML Output Format
130

131
- **`html4tags=False`**: Use XHTML-style empty elements (`<br />`)
132
- **`html4tags=True`**: Use HTML4-style empty elements (`<br>`)
133

134
### Tab Handling
135

136
- **`tab_width=4`**: Number of spaces each tab character represents in code blocks
137

138
### Security Options
139

140
- **`safe_mode=None`**: Allow all HTML tags (default)
141
- **`safe_mode="escape"`**: Escape HTML characters (`<` becomes `&lt;`)
142
- **`safe_mode="replace"`**: Replace HTML with `[HTML_REMOVED]` placeholder
143

144
### Extras Configuration
145

146
Extras can be specified as:
147
- **List of strings**: `extras=["tables", "footnotes"]`
148
- **Dictionary**: `extras={"tables": None, "header-ids": {"prefix": "section-"}}`
149

150
### Link Pattern Configuration
151

152
Auto-linking patterns as tuples of `(compiled_regex, replacement)`:
153
- **String replacement**: `(re.compile(r'#(\d+)'), r'https://github.com/issues/\1')`
154
- **Callable replacement**: `(re.compile(r'@(\w+)'), lambda m: f'<a href="/users/{m.group(1)}">@{m.group(1)}</a>')`
155

156
### File Variable Processing
157

158
When `use_file_vars=True`, markdown2 looks for Emacs-style file variables like:
159
```markdown
160
<!-- markdown-extras: footnotes, tables -->
161
```