repository·main·Indexed 22 days ago
https://github.com/facelessuser/pymdown-extensionsA suite of specialized extensions for the Python Markdown library, version 8.1.2, designed to provide advanced Markdown features and enhanced processing capabilities, including the Arithmatex extension for LaTeX math equations.
MagicLink is an extension designed to enhance link handling in Markdown. Its primary capabilities include:
#!md <https://www.link.com>. If enabled, repository link shortening will still apply to these bracketed links.The smartsymbols extension provides syntax for automatically replacing common text patterns with special characters like trademarks, arrows, fractions, and ordinal numbers. It is designed to be used alongside Python Markdown's smarty extension rather than replacing it.
Supported replacements include:
(tm), (c), (r)-->, <--, <-->+/-, =/=1/4, etc.1st, 2nd, etc.c/o| Markdown | Result |
| :--- | :--- |
| `(tm)` | (tm) |
| `(c)` | (c) |
| `(r)` | (r) |
| `c/o` | c/o |
| `+/-` | +/- |
| `-->` | --> |
| `<--` | <-- |
| `<-->` | <--> |
| `=/=` | =/= |
| `1/4` | 1/4 |
| `1st` | 1st |The Keys extension uses the + symbol to denote key combinations. A sequence of key presses is wrapped in double plus signs (++), and individual keys within the sequence are separated by a single plus sign (+).
Example syntax:
++ctrl+alt+delete++
++ctrl+alt+delete++FancyLists supports several ordered list marker styles. Using a different list type (e.g., switching from dots to parentheses) will start a new list.
1. or 1)a. or a)A. or A)i. or i)I. or I)#. or #) . These markers inherit the type of the current list as long as they use the same convention (. or )). If used to start a new list, decimal format is assumed. Note: Requires pymdownx.saneheaders to be enabled.1) Item 1
2) Item 2
i. Item 1
ii. Item 2
a. Item a
b. Item b
#. Item 1
#. Item 2FancyLists automatically creates a new list or restarts a list when the list type changes. A new list is triggered by:
- to 1.).1. to 1)).a. to A.).Generic list items (using the #. syntax) inherit the type from the current list. If they start a new list, they default to the decimal type. As long as the marker is consistent with the current list type, they will append to the existing list rather than creating a new one.
Note on Uppercase Alphabetical Lists: To avoid false positives with names starting with an initial (e.g., B. Russell), use two spaces after the marker instead of the standard one.
B. Russell was an English philosopher.
A. This is a list.If url_download is enabled, you can use URLs instead of local file paths.
Important Constraints:
Configuration Options:
url_download: Enables/disables URL snippets.url_max_size: Maximum size of the downloaded content (default applies unless set to 0 to ignore).url_timeout: Timeout for the request (default applies unless set to 0 to ignore).url_request_headers: A dictionary of HTTP headers to include in every request.max_retries: Maximum retry attempts for 429 (Too Many Requests) status codes (default: 3).backoff_factor: Factor for linear backoff (default: 2).Snippets is a preprocessor extension that allows you to insert Markdown or HTML content from external files into your current document. This is useful for maintaining single sources of truth for content (like hyperlinks or code examples) used across multiple files.
Key Behaviors:
url_download can expose the renderer to SSRF-style risks.SuperFences handles most exceptions in validators and formatters gracefully by ignoring the failing component.
To prevent silent failures and halt Markdown parsing, raise a SuperFencesException. This will bubble up and display both the SuperFencesException and the original cause.
from pymdownx.superfences import SuperFencesException
def custom_validator_except(language, inputs, options, attrs, md):
try:
# ... logic that might raise KeyError ...
if inputs['opt'] != "A":
return False
except KeyError as e:
raise SuperFencesException from e
return Truedef custom_validator_except(language, inputs, options, attrs, md):
"""Custom validator."""
okay = True
try:
for k in inputs.keys():
if k != 'opt':
okay = False
break
if okay:
if inputs['opt'] != "A":
okay = False
else:
options['opt'] = inputs['opt']
except KeyError as e:
raise SuperFencesException from e
return okayBy default, Python Markdown recognizes headers even if there is no space after the hashes (e.g., ##Header).
SaneHeaders modifies this behavior to follow a stricter rule: a line is only treated as a header if there is at least one space following the # characters. This allows other syntaxes that use # at the start of a line—such as issue links (#998), tags (#tag), or FancyLists ordered list markers (#. )—to coexist with standard Markdown headers without being incorrectly parsed as headers.
## Header (Recognized as header)
##Not a Header (Not recognized as header)The Mermaid integration relies on a custom JavaScript loader (often named extra-loader.js) that performs the following steps:
<diagram-div> custom element using the Shadow DOM to encapsulate Mermaid content and prevent ID collisions.window.mermaidConfig. If not found, it uses a defaultConfig. It then calls mermaid.initialize(config).pre.mermaid) or <diagram-div> elements.<diagram-div> shadow root, replacing the original text source to keep the UI clean.When level_class is enabled (default is True), the extension adds a class to the outer .progress container based on the progress_increment setting.
For example, if progress_increment is set to 20, the extension will generate classes like .progress-20plus, .progress-40plus, etc., depending on the progress value. This allows you to change the color of the progress bar at specific thresholds using CSS:
.progress-100plus .progress-bar { background-color: #00e676; }
.progress-80plus .progress-bar { background-color: #fbc02d; }