fstmd
Advanced tools
A pure Finite State Transducer (FST) Markdown to HTML converter for Python 3.13+.
pip install fstmd
Or install from source:
git clone https://github.com/fstmd/fstmd.git
cd fstmd
pip install -e .
from fstmd import Markdown
# Create a parser (safe mode by default)
md = Markdown(mode="safe")
# Render Markdown to HTML
html = md.render("**Hello** *world*")
print(html)
# Output: <p><strong>Hello</strong> <em>world</em></p>
| Feature | Syntax | Output |
|---|---|---|
| Bold | **text** | <strong>text</strong> |
| Italic | *text* | <em>text</em> |
| Bold+Italic | ***text*** | <strong><em>text</em></strong> |
| Headings | # H1 to ###### H6 | <h1> to <h6> |
| Unordered Lists | - item | <ul><li>item</li></ul> |
| Paragraphs | Blank line separated | <p>...</p> |
from fstmd import Markdown
# Safe mode (default) - escapes all HTML
md = Markdown(mode="safe")
# Raw mode - passes through HTML (use with trusted input only!)
md = Markdown(mode="raw")
# Strict mode - raises exceptions on security issues
md = Markdown(mode="safe", strict=True)
# Render markdown
html = md.render("# Hello **World**")
# Always render safely, regardless of instance mode
safe_html = md.render_safe("<script>alert(1)</script>")
from fstmd.parser import render, render_unsafe
# Quick render with caching
html = render("**bold**")
# Render without escaping (dangerous!)
html = render_unsafe("<b>raw html</b>")
FSTMD is designed with security as a primary concern:
All HTML special characters are escaped:
< → <> → >& → &" → "' → 'md = Markdown(mode="safe")
result = md.render("<script>alert('xss')</script>")
# Output: <p><script>alert('xss')</script></p>
The library detects and can reject:
<script> tagsjavascript: URLsvbscript: URLsdata: URLs (except safe image types)FSTMD uses a Mealy Machine (FST) where output is generated during state transitions.
┌─────────────────────────────────────────────────────────────────┐
│ INLINE FST STATES │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌───────┐ '*' ┌──────────┐ '*' ┌──────────┐ │
│ │ TEXT │───────────►│ STAR_ONE │──────────►│ STAR_TWO │ │
│ └───┬───┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │
│ │ other │ other │ other │
│ ▼ ▼ ▼ │
│ output char start italic start bold │
│ │
│ ┌───────────┐ ┌────────────┐ │
│ │ IN_ITALIC │◄───────│ STAR_ONE │ (from TEXT with '*') │
│ └─────┬─────┘ └────────────┘ │
│ │ '*' │
│ ▼ │
│ ┌──────────────┐ │
│ │ close italic │────► output </em>, goto TEXT │
│ └──────────────┘ │
│ │
│ ┌──────────┐ ┌───────────────┐ │
│ │ IN_BOLD │◄────────│ STAR_TWO │ (from STAR_ONE) │
│ └────┬─────┘ └───────────────┘ │
│ │ '**' │
│ ▼ │
│ ┌─────────────┐ │
│ │ close bold │────────► output </strong> │
│ └─────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────┐
│ BLOCK FST STATES │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ │
│ │ START │ ─────────────────────────────────────────────┐ │
│ └────┬─────┘ │ │
│ │ │ │
│ ┌───┴───┐ '#' ┌──────────┐ │ │
│ │ LINE │──────────►│ HEADING │──► count #'s, emit <hN> │ │
│ │ START │ └──────────┘ │ │
│ └───┬───┘ │ │
│ │ │ │
│ │ '-' ┌───────────────┐ │ │
│ ├─────────►│ LIST_ITEM │──► emit <li> │ │
│ │ └───────────────┘ │ │
│ │ │ │
│ │ '\n' ┌───────────────┐ │ │
│ ├─────────►│ BLANK_LINE │──► close paragraph │ │
│ │ └───────────────┘ │ │
│ │ │ │
│ │ other ┌───────────────┐ │ │
│ └─────────►│ PARAGRAPH │──► emit <p> │ │
│ └───────────────┘ │ │
│ │
└─────────────────────────────────────────────────────────────────┘
* vs ** vs ***| Operation | Time Complexity | Space Complexity |
|---|---|---|
| Parse | O(N) | O(N) |
| Per character | O(1) | O(1) |
Tested on Python 3.13 with a medium-sized document (~500 chars):
| Library | Avg Time (ms) | Throughput | Relative |
|---|---|---|---|
| FSTMD | 0.05 | 10M chars/sec | 1.0x |
| markdown-it-py | 0.15 | 3.3M chars/sec | 0.33x |
| Python-Markdown | 0.30 | 1.7M chars/sec | 0.17x |
| CommonMark-Py | 0.35 | 1.4M chars/sec | 0.14x |
Note: Benchmarks vary by hardware and document structure.
Run benchmarks yourself:
from fstmd.benchmarks import run_benchmarks, print_benchmark_results
results = run_benchmarks()
print_benchmark_results(results)
FSTMD focuses on speed and simplicity. It does not support:
For full CommonMark compliance, use markdown-it-py.
# Clone the repository
git clone https://github.com/fstmd/fstmd.git
cd fstmd
# Install with dev dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Type checking
mypy fstmd
# Linting
ruff check fstmd
fstmd/
├── __init__.py # Package exports
├── __main__.py # CLI entry point
├── parser.py # High-level Markdown class
├── exceptions.py # Custom exceptions
├── core/
│ ├── __init__.py
│ ├── fsm.py # Main FST engine
│ ├── states.py # State definitions
│ ├── transitions.py # Transition table
│ └── safe_html.py # HTML escaping
├── benchmarks/
│ ├── __init__.py
│ └── runner.py # Benchmark utilities
└── tests/
├── conftest.py
├── test_inline.py
├── test_blocks.py
├── test_security.py
├── test_fsm.py
└── test_integration.py
# Install build tools
pip install build twine
# Build distribution
python -m build
# Check the build
twine check dist/*
# Upload to TestPyPI first
twine upload --repository testpypi dist/*
# Upload to PyPI
twine upload dist/*
Contributions are welcome! Please:
pytest)mypy fstmd)ruff check fstmd)MIT License - see LICENSE file.
Inspired by:
Made with ❤️ for fast, secure Markdown parsing.
FAQs
Finite-State Markdown Engine - O(N) single-pass Markdown to HTML converter using pure FST
We found that fstmd demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
GitHub has revoked npm classic tokens for publishing; maintainers must migrate, but OpenJS warns OIDC trusted publishing still has risky gaps for critical projects.
Security News
Rust’s crates.io team is advancing an RFC to add a Security tab that surfaces RustSec vulnerability and unsoundness advisories directly on crate pages.
Security News
/Research
Socket found a Rust typosquat (finch-rust) that loads sha-rust to steal credentials, using impersonation and an unpinned dependency to auto-deliver updates.