HTML-Markdown Converter

A powerful, bidirectional converter between HTML and Markdown with both CLI and VS Code extension support.

✨ Features

• 🔄 Bidirectional Conversion: Convert HTML to Markdown and Markdown to HTML
• 💻 CLI Tool: Easy-to-use command-line interface
• 🎨 VS Code Extension: Integrate seamlessly into your workflow
• ⚡ Fast & Reliable: Built on Turndown and markdown-it
• 🛠️ Customizable: Configure conversion options to suit your needs
• 📦 Zero Config: Works out of the box with sensible defaults

📦 Installation

CLI Tool

Install globally to use from anywhere:

npm install -g html-md-converter

Or use locally in your project:

npm install html-md-converter

VS Code Extension

Search for "HTML-Markdown Converter" in the VS Code Extensions marketplace, or install from the command palette:

1. Open VS Code
2. Press Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux)
3. Type "Install Extensions"
4. Search for "HTML-Markdown Converter"

🚀 Usage

CLI

HTML to Markdown

# Convert a file
html-to-md input.html

# Specify output file
html-to-md input.html -o output.md

# Output to stdout
html-to-md input.html --stdout

# Customize heading style
html-to-md input.html --heading-style setext

# Customize code block style
html-to-md input.html --code-block-style indented

Markdown to HTML

# Convert a file
md-to-html input.md

# Specify output file
md-to-html input.md -o output.html

# Output to stdout
md-to-html input.md --stdout

# Disable HTML tags in source
md-to-html input.md --no-html

# Disable automatic link detection
md-to-html input.md --no-linkify

Programmatic API

import { htmlToMarkdown, markdownToHtml } from 'html-md-converter';

// HTML to Markdown
const html = '<h1>Hello World</h1><p>This is a paragraph.</p>';
const markdown = htmlToMarkdown(html);
console.log(markdown);
// # Hello World
//
// This is a paragraph.

// Markdown to HTML
const md = '# Hello World\n\nThis is a paragraph.';
const htmlOutput = markdownToHtml(md);
console.log(htmlOutput);
// <h1>Hello World</h1>
// <p>This is a paragraph.</p>

Advanced Options

// HTML to Markdown with options
const markdown = htmlToMarkdown(html, {
  headingStyle: 'setext', // 'atx' or 'setext'
  codeBlockStyle: 'indented', // 'fenced' or 'indented'
  bulletListMarker: '-', // '-', '+', or '*'
  emDelimiter: '_', // '_' or '*'
  strongDelimiter: '**' // '**' or '__'
});

// Markdown to HTML with options
const html = markdownToHtml(markdown, {
  html: true, // Enable HTML tags in source
  linkify: true, // Auto-detect URLs and convert to links
  typographer: true, // Enable smart quotes and other typographic replacements
  breaks: false // Convert '\n' in paragraphs into <br>
});

VS Code Extension

Once installed, the extension provides the following commands:

1. Convert HTML to Markdown
   • Open an HTML file or select HTML content
   • Press Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux)
   • Type "Convert HTML to Markdown"
2. Convert Markdown to HTML
   • Open a Markdown file or select Markdown content
   • Press Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows/Linux)
   • Type "Convert Markdown to HTML"

The extension also provides:

• Context menu options for quick conversion
• Keyboard shortcuts: Ctrl+Alt+M for HTML→MD, Ctrl+Alt+H for MD→HTML
• Real-time preview panel

🔧 Configuration

CLI Options

html-to-md

| Option | Description | Default | | ---------------------------- | ---------------------------------- | -------------------- | | -o, --output <file> | Output file path | Auto-generated (.md) | | -s, --stdout | Output to stdout | false | | --heading-style <style> | Heading style (atx/setext) | atx | | --code-block-style <style> | Code block style (fenced/indented) | fenced |

md-to-html

| Option | Description | Default | | --------------------- | -------------------------------- | ---------------------- | | -o, --output <file> | Output file path | Auto-generated (.html) | | -s, --stdout | Output to stdout | false | | --no-html | Disable HTML tags in source | false | | --no-linkify | Disable auto link detection | false | | --no-typographer | Disable typographic replacements | false |

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Setup

# Clone the repository
git clone https://github.com/jasdeepkhalsa/html-md-converter.git
cd html-md-converter

# Install dependencies
npm install

# Run tests
npm test

# Run linter
npm run lint

# Format code
npm run format

📝 Examples

Example 1: Converting HTML Blog Post

html-to-md blog-post.html -o blog-post.md

Example 2: Converting Markdown Documentation

md-to-html README.md -o index.html

Example 3: Batch Processing

# Convert all HTML files in a directory
for file in *.html; do html-to-md "$file"; done

# Convert all Markdown files
for file in *.md; do md-to-html "$file"; done

Example 4: Piping with Other Tools

# Fetch HTML from URL and convert
curl https://example.com | html-to-md /dev/stdin --stdout

# Convert and preview in browser
md-to-html README.md --stdout | open -f -a "Google Chrome"

🧪 Testing

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run with coverage
npm test -- --coverage

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Turndown - HTML to Markdown converter
• markdown-it - Markdown parser and renderer

📮 Support

• 🐛 Report a bug
• 💡 Request a feature
• 📖 Documentation

🗺️ Roadmap

• [ ] Add support for custom Turndown rules
• [ ] Add support for markdown-it plugins
• [ ] Batch conversion UI
• [ ] Configuration file support (.converterrc)
• [ ] Support for more input/output formats
• [ ] Interactive CLI mode
• [ ] Web-based converter interface

Made with ❤️ by the open source community