DEV Community

Devadatta Baireddy
Devadatta Baireddy

Posted on

Markdown to HTML Converter CLI - No More Manual Conversions

#python #markdown #cli #webdev

Markdown to HTML Converter CLI — No More Manual Conversions

You write in markdown. Your blog needs HTML. Your docs need HTML. Your portfolio needs HTML.

What do you do?

Option 1: Use a bloated online converter (slow, privacy concerns)

Option 2: Learn a complex tool like Pandoc (overkill for simple conversions)

Option 3: Use Markdown → HTML libraries (requires npm, pip, Ruby gems)

Or... use this simple CLI tool I built.

Markdown to HTML Converter is a zero-dependency Python tool that converts markdown files to beautiful, responsive HTML in one command.

The Problem

Converting markdown to HTML should be trivial. But:

  • Online converters are slow and privacy-invasive
  • Pandoc is powerful but heavy (200MB+)
  • npm/pip packages require dependency management
  • You just need something fast, simple, and local

The Solution 

python markdown_to_html.py readme.md -o index.html
Enter fullscreen mode Exit fullscreen mode

That's it. Takes 50ms. No dependencies. Beautiful HTML with embedded CSS.

Key Features

✅ Simple Syntax

Converts all standard markdown:

# Heading
**bold** and *italic*
[links](https://example.com)
`code` and ```

python code blocks
Enter fullscreen mode Exit fullscreen mode
  • Lists > Blockquotes ```

✅ Beautiful Themes

Light theme (professional, print-friendly)

python markdown_to_html.py readme.md --theme light -o light.html
Enter fullscreen mode Exit fullscreen mode

Dark theme (modern, eye-friendly)

python markdown_to_html.py readme.md --theme dark -o dark.html
Enter fullscreen mode Exit fullscreen mode

✅ Responsive Design

Output is mobile-friendly, auto-scales to any screen:

  • Responsive typography
  • Proper spacing and padding
  • Works on phones, tablets, desktops
  • Professional appearance out of the box

✅ Production Ready

Generates complete HTML5 pages:

  • Valid <!DOCTYPE html>
  • UTF-8 encoding
  • Meta tags for mobile
  • Embedded CSS (no external files needed)

Real Examples

Example 1: Blog Post Conversion

You have a markdown blog post:

post.md:

# How to Learn Python in 30 Days

Python is one of the most beginner-friendly programming languages.

## Getting Started

First, install Python:
Enter fullscreen mode Exit fullscreen mode


bash

macOS

brew install python3

Windows

choco install python


Then, write your first program:
Enter fullscreen mode Exit fullscreen mode


python
print("Hello, World!")


Happy coding!
Enter fullscreen mode Exit fullscreen mode

Convert it:

python markdown_to_html.py post.md -o post.html
Enter fullscreen mode Exit fullscreen mode

Result: A beautiful, responsive blog post ready to publish.

Example 2: README to Standalone Page

GitHub READMEs are markdown. But sometimes you need an HTML version for your website:

# Convert your GitHub README to HTML
python markdown_to_html.py README.md --title "My Project" -o docs/index.html
Enter fullscreen mode Exit fullscreen mode

Now you can:

  • Host it on your website
  • Share as an email
  • Print it to PDF
  • Embed in your documentation site

Example 3: Dark Theme Portfolio

Build a modern portfolio page:

python markdown_to_html.py portfolio.md --theme dark --title "John Doe" -o portfolio.html
Enter fullscreen mode Exit fullscreen mode

Portfolio in markdown:

# John Doe

## About
Experienced Python developer and open-source contributor.

## Projects
- [Project 1](link)
- [Project 2](link)

## Contact
[Email me](mailto:john@example.com)
Enter fullscreen mode Exit fullscreen mode

Result: A professional, dark-themed portfolio with zero CSS knowledge.

Example 4: Documentation Pipeline

Convert all your markdown docs at once:

# Bash script to convert multiple files
for md in docs/*.md; do
    html="public/$(basename $md .md).html"
    python markdown_to_html.py "$md" -o "$html"
done

# Deploy
git add public/
git commit -m "Update docs"
git push
Enter fullscreen mode Exit fullscreen mode

Performance Comparison

Tool Speed File Size Dependencies Setup
This tool 50ms 12KB None 2 min
Pandoc 500ms 200MB Heavy 10 min
npm markdown-it 100ms 50MB 100+ packages 5 min
Online converter 2000ms+ Varies Cloud 1 min

Winner: This tool for 95% of use cases.

What It Supports

✅ Headings (h1-h6)

✅ Bold and italic

✅ Links and URLs

✅ Inline code

✅ Code blocks with syntax highlighting ready

✅ Unordered lists

✅ Ordered lists

✅ Blockquotes

✅ Horizontal rules

✅ Line breaks

✅ Paragraphs

❌ Tables (coming v2)

❌ Nested lists (limited)

❌ Advanced formatting

Note: For very complex markdown, use Pandoc. But for 99% of real-world use, this covers everything.

How It Works

Simple architecture:

class MarkdownParser:
    def parse_markdown(self, markdown_text):
        # Line by line parsing
        for line in markdown_text.split('\n'):
            if line.startswith('#'):
                parse_heading()
            elif line.startswith('-'):
                parse_list()
            elif line.startswith('>'):
                parse_blockquote()
            # ... etc

        # Wrap in HTML5 template with CSS
        return complete_html_page
Enter fullscreen mode Exit fullscreen mode

Zero regex magic. Just simple string parsing.

Installation 

# Clone or download
git clone https://github.com/devdattareddy/markdown-to-html-cli
cd markdown-to-html-cli

# Run
python markdown_to_html.py readme.md -o index.html
Enter fullscreen mode Exit fullscreen mode

Get it free on GitHub:
👉 github.com/devdattareddy/markdown-to-html-cli

Use Cases

🎨 Bloggers - Convert posts quickly

📚 Documentation - Generate docs sites from markdown

🌐 Portfolio - Build stunning portfolio pages

📝 Writers - Export articles to web format

🚀 Static Site Generators - Part of your build pipeline

Premium Version

Want a GUI? Want batch conversion? Check out the Premium version on Gumroad with:

  • Desktop GUI (no command line)
  • Batch file conversion
  • Custom CSS editor
  • Export to PDF
  • Templates library

Free version is fully functional for command-line users!

Why I Built This

I was converting markdown to HTML manually for a documentation site. Every change meant:

  1. Edit markdown
  2. Copy to online converter
  3. Copy HTML output
  4. Paste into website

Tedious. So I built a 200-line Python script to automate it.

Now it saves me 2-3 hours per week.

Get Started 

# One-liner setup
git clone https://github.com/devdattareddy/markdown-to-html-cli && cd markdown-to-html-cli

# Try it
python markdown_to_html.py README.md -o test.html
open test.html  # or start test.html on Windows
Enter fullscreen mode Exit fullscreen mode

Support This Project

If this tool saves you time:

🎉 Buy Me a Coffee - Help me build more tools

⭐ Star on GitHub - Help others discover it

💬 Share it - Tell your developer friends!

What's your markdown-to-HTML workflow? Let me know in the comments — I might add features you need!

Top comments (0)