A simple, original HTML-to-Markdown converter for webpages, local .html files, and pasted HTML. Run it with no arguments, paste a URL, and it writes a clean .md file for you.

• Converts headings, paragraphs, links, images, lists, blockquotes, inline code, code blocks, and tables.
• Uses --content-mode auto by default to keep likely article content and skip obvious site chrome.
• Supports --content-mode full when you want the whole page body.
• Supports --plain-text when maximum text retention matters more than Markdown formatting.
• Supports simple selectors such as --include-selector article and --exclude-selector nav,footer,.ad.
• Supports batch conversion with glob input and an output directory.
• Accepts a URL, a local file path, or stdin.
• Writes Markdown to stdout or a .md file.
• Uses only the Python standard library.

From the plugin root:

python html2md.py

Then paste the webpage URL or local HTML file path. The Markdown file will be generated in the current directory.

On Windows, if python points to Python 2, use:

html2md.cmd

You can also run the script directly:

python scripts/html_to_markdown.py "https://example.com" --output example.md

Or install it locally and use the html2md command:

python -m pip install -e .
html2md

Convert a local file:

python html2md.py examples/sample.html --output sample.md

Keep the full page body instead of automatic article extraction:

python html2md.py "https://en.wikipedia.org/wiki/GitHub" --output github-full.md --content-mode full

Keep more visible text with simpler formatting:

python html2md.py "https://en.wikipedia.org/wiki/GitHub" --output github.txt.md --plain-text

Convert only a selected part of the page:

python html2md.py page.html --output article.md --include-selector article --exclude-selector nav,footer,.ad

Batch convert local HTML files:

python html2md.py --input "pages/*.html" --output-dir md

If a remote webpage times out, increase the timeout and retry count:

python html2md.py "https://en.wikipedia.org/wiki/GitHub" --output github.md --timeout 180 --retries 5

Convert pasted HTML:

Get-Content page.html | py -3 scripts/html_to_markdown.py - --output page.md

Run tests:

py -3 -m unittest discover -s tests

Run the local benchmark:

py -3 benchmarks/bench_converter.py

html-2-markdown/
  html2md.py                  # Friendly Python entrypoint
  html2md.cmd                 # Windows launcher
  html2md                     # Unix-like launcher
  scripts/html_to_markdown.py # Core converter
  tests/                      # Unit tests
  benchmarks/                 # Local benchmark
  examples/                   # Sample input and output
  .github/workflows/          # GitHub Actions tests
  .codex-plugin/              # Optional Codex plugin metadata

This repository is already shaped as a Codex plugin. After cloning it, install or load it through your Codex plugin workflow.

Created and maintained by Ryan Zhang.

Open-sourcing this plugin is okay. For the safest public release:

• Use an open-source license such as MIT.
• Do not include copied website content in the repository unless you have permission.
• Respect website terms, robots policies, copyright, paywalls, and login requirements when converting remote pages.
• Preserve attribution when sharing converted content.

MIT