markdown_to_mrkdwn¶
A lightweight, efficient library for converting standard Markdown to Slack’s mrkdwn format.
Features¶
Fast and lightweight conversion from Markdown to Slack’s mrkdwn format
No external dependencies
Comprehensive support for Markdown elements: - Headings (H1–H6) - Text formatting (bold, italic, strikethrough) - Lists (ordered and unordered, with nesting) - Ordered lists (numbered lists with proper indentation) - Task lists (checked and unchecked items) - Tables (with header formatting) - Links and image references - Code blocks (with language specification preserved) - Blockquotes - Horizontal rules
Preserves code blocks without converting their contents
Handles special characters and edge cases
Installation¶
Install from PyPI using pip:
pip install markdown_to_mrkdwn
Requirements: - Python 3.8 or higher
Usage¶
Basic Usage¶
from markdown_to_mrkdwn import SlackMarkdownConverter
# Create a converter instance
converter = SlackMarkdownConverter()
# Convert markdown to mrkdwn
markdown_text = """
# Heading 1
**Bold text**
- List item
[Link](https://example.com)
~~Strikethrough text~~
"""
mrkdwn_text = converter.convert(markdown_text)
print(mrkdwn_text)
Example Output¶
*Heading 1*
*Bold text*
• List item
<https://example.com|Link>
~Strikethrough text~
Supported Conversions¶
Markdown |
Slack mrkdwn |
---|---|
# Heading |
*Heading* |
**Bold** / __Bold__ |
*Bold* |
*Italic* |
_Italic_ |
~~Strikethrough~~ |
~Strikethrough~ |
[Link](https://example.com) |
<https://example.com|Link> |
 |
<https://example.com/img.png> |
- List item |
• List item |
1. Ordered item |
1. Ordered item |
- [ ] Task |
• ☐ Task |
- [x] Task |
• ☑ Task |
> Quote |
> Quote |
`` Code `` |
`` Code `` |
`` ``python ` |
`` ``python ` |
— |
────────── |
Tables |
Simple text tables with bold headers |
Testing in Slack¶
You can test the output in Slack Block Kit Builder: https://app.slack.com/block-kit-builder/
Advanced Usage¶
Custom Encoding¶
You can specify a custom encoding when initializing the converter.
Plugin System¶
You can extend the converter with your own plugins.
Function Plugin Example:
from markdown_to_mrkdwn.converter import SlackMarkdownConverter
def to_upper(line):
return line.upper()
converter = SlackMarkdownConverter()
converter.register_plugin(
name="to_upper",
converter_func=to_upper,
priority=10,
scope="line",
timing="after"
)
print(converter.convert("hello")) # Output: HELLO
Regex Plugin Example:
# Add comma to thousands
converter.register_regex_plugin(
name="add_comma_to_thousands",
pattern=r"(?<=\\d)(?=(\\d{3})+(?!\\d))",
replacement=",",
priority=10,
timing="after"
)
print(converter.convert("1234567")) # Output: 1,234,567
# Mask email addresses
converter.register_regex_plugin(
name="mask_email",
pattern=r"[a-zA-Z0-9_.+-]+@[a-zA-Z0-9-]+\\.[a-zA-Z0-9-.]+",
replacement="[EMAIL]",
priority=20,
timing="after"
)
print(converter.convert("Contact: test.user@example.com")) # Output: Contact: [EMAIL]
priority controls execution order (lower runs first)
timing can be “before” or “after” (default: “after”)
scope is always “line” for regex plugins
Error Handling¶
If an error occurs during conversion, the original markdown text will be returned.
try:
mrkdwn_text = converter.convert(markdown_text)
except Exception as e:
print(f"Conversion error: {e}")
Contributing¶
Contributions are welcome!
Fork the repository
Create a feature branch: git checkout -b feature/your-feature-name
Commit your changes: git commit -am ‘Add some feature’
Push to the branch: git push origin feature/your-feature-name
Submit a pull request
Please make sure to update tests as appropriate.
License¶
This project is licensed under the MIT License. See the [LICENSE](../LICENSE) file for details.
Contents: