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>
![Image](https://example.com/img.png)	<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:

markdown_to_mrkdwn
- markdown_to_mrkdwn package