Initial release

Author: riainzhang

.codex-plugin/plugin.json

@@ -0,0 +1,27 @@
+{
+  "name": "html-to-markdown",
+  "version": "0.3.0",
+  "description": "Convert HTML webpages and files into clean Markdown with easy defaults and advanced extraction.",
+  "author": {
+    "name": "Ryan Zhang",
+    "url": "https://github.com/riainzhang"
+  },
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "HTML to Markdown",
+    "shortDescription": "Convert HTML pages to Markdown files.",
+    "longDescription": "HTML to Markdown gives Codex a local workflow for converting HTML from webpages, files, or stdin into portable Markdown documents with article extraction, selector filtering, batch conversion, table rendering, and plain-text fallback.",
+    "developerName": "Ryan Zhang",
+    "websiteURL": "https://github.com/riainzhang",
+    "category": "Productivity",
+    "capabilities": [
+      "HTML conversion",
+      "Markdown export",
+      "Article extraction",
+      "Table rendering",
+      "Batch conversion",
+      "Selector filtering"
+    ],
+    "defaultPrompt": "Convert this HTML webpage to a Markdown file."
+  }
+}

.github/workflows/tests.yml

@@ -0,0 +1,21 @@
+name: Tests
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Run tests
+        run: python -m unittest discover -s tests
+      - name: Run benchmark smoke test
+        run: python benchmarks/bench_converter.py

.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.pyc
+*.pyo
+.DS_Store
+Thumbs.db
+*.egg-info/
+build/
+dist/
+.venv/
+venv/
+
+# Ignore generated root-level conversion outputs while keeping project docs.
+/*.md
+!/README.md
+!/CHANGELOG.md

CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.3.0
+
+- Added friendly root entrypoints: `html2md.py`, `html2md.cmd`, and `html2md`.
+- Added selector filtering with `--include-selector` and `--exclude-selector`.
+- Added batch conversion with `--input` and `--output-dir`.
+- Added GitHub Actions test workflow.
+- Added local benchmark and expanded tests.
+
+## 0.2.0
+
+- Replaced the initial stream renderer with an original tree-based renderer.
+- Added article extraction, table rendering, and plain-text fallback.
+
+## 0.1.0
+
+- Initial Codex plugin scaffold and Python converter.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ryan Zhang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,140 @@
+# HTML to Markdown
+
+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.
+
+## What it does
+
+- 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.
+
+## Quick Start
+
+From the plugin root:
+
+```bash
+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:
+
+```powershell
+html2md.cmd
+```
+
+You can also run the script directly:
+
+```bash
+python scripts/html_to_markdown.py "https://example.com" --output example.md
+```
+
+Or install it locally and use the `html2md` command:
+
+```bash
+python -m pip install -e .
+html2md
+```
+
+## Useful Commands
+
+Convert a local file:
+
+```bash
+python html2md.py examples/sample.html --output sample.md
+```
+
+Keep the full page body instead of automatic article extraction:
+
+```bash
+python html2md.py "https://en.wikipedia.org/wiki/GitHub" --output github-full.md --content-mode full
+```
+
+Keep more visible text with simpler formatting:
+
+```bash
+python html2md.py "https://en.wikipedia.org/wiki/GitHub" --output github.txt.md --plain-text
+```
+
+Convert only a selected part of the page:
+
+```bash
+python html2md.py page.html --output article.md --include-selector article --exclude-selector nav,footer,.ad
+```
+
+Batch convert local HTML files:
+
+```bash
+python html2md.py --input "pages/*.html" --output-dir md
+```
+
+If a remote webpage times out, increase the timeout and retry count:
+
+```bash
+python html2md.py "https://en.wikipedia.org/wiki/GitHub" --output github.md --timeout 180 --retries 5
+```
+
+Convert pasted HTML:
+
+```bash
+Get-Content page.html | py -3 scripts/html_to_markdown.py - --output page.md
+```
+
+## Quality And Speed
+
+Run tests:
+
+```bash
+py -3 -m unittest discover -s tests
+```
+
+Run the local benchmark:
+
+```bash
+py -3 benchmarks/bench_converter.py
+```
+
+## Project Structure
+
+```text
+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
+```
+
+## Installing as a Codex plugin
+
+This repository is already shaped as a Codex plugin. After cloning it, install or load it through your Codex plugin workflow.
+
+## Author
+
+Created and maintained by [Ryan Zhang](https://github.com/riainzhang).
+
+## Open access and legal notes
+
+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.
+
+## License
+
+MIT

benchmarks/bench_converter.py

@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+"""Run a small local benchmark for the converter."""
+
+import tempfile
+import time
+from pathlib import Path
+import sys
+
+
+ROOT = Path(__file__).resolve().parents[1]
+sys.path.insert(0, str(ROOT / "scripts"))
+
+import html_to_markdown as converter
+
+
+SAMPLE_ARTICLE = """
+<!doctype html>
+<html>
+<head><title>Benchmark Article</title></head>
+<body>
+<nav>Home Products Login</nav>
+<main id="content">
+<h1>Benchmark Article</h1>
+<p>This benchmark page contains links, tables, nested lists, blockquotes, and code.</p>
+<p>Visit <a href="/docs">the documentation</a> for more details.</p>
+<table>
+<tr><th>Name</th><th>Value</th></tr>
+<tr><td>Alpha</td><td>One</td></tr>
+<tr><td>Beta</td><td>Two</td></tr>
+</table>
+<ul>
+<li>Fast defaults<ul><li>No dependencies</li><li>Interactive mode</li></ul></li>
+<li>Batch mode</li>
+</ul>
+<blockquote><p>Readable Markdown is the goal.</p></blockquote>
+<pre><code>print("hello")</code></pre>
+</main>
+<footer>Contact Subscribe Legal</footer>
+</body>
+</html>
+"""
+
+
+def main() -> None:
+    with tempfile.NamedTemporaryFile("w", suffix=".html", delete=False, encoding="utf-8") as handle:
+        handle.write(SAMPLE_ARTICLE)
+        source = handle.name
+
+    iterations = 200
+    started = time.perf_counter()
+    markdown = ""
+    try:
+        for _ in range(iterations):
+            markdown = converter.convert(source, content_mode="auto")
+    finally:
+        Path(source).unlink(missing_ok=True)
+    elapsed = time.perf_counter() - started
+
+    checks = {
+        "article text": "Benchmark Article" in markdown,
+        "table": "| Name | Value |" in markdown,
+        "nested list": "  - No dependencies" in markdown,
+        "site chrome removed": "Home Products Login" not in markdown and "Contact Subscribe Legal" not in markdown,
+    }
+    passed = sum(1 for value in checks.values() if value)
+    pages_per_second = iterations / elapsed if elapsed else 0
+
+    print("HTML to Markdown benchmark")
+    print("Iterations: {}".format(iterations))
+    print("Elapsed: {:.3f}s".format(elapsed))
+    print("Throughput: {:.1f} pages/sec".format(pages_per_second))
+    print("Output size: {} chars".format(len(markdown)))
+    print("Quality checks: {}/{} passed".format(passed, len(checks)))
+    for name, ok in checks.items():
+        print("- {}: {}".format(name, "ok" if ok else "failed"))
+
+
+if __name__ == "__main__":
+    main()

examples/sample.html

@@ -0,0 +1,21 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>Sample HTML Page</title>
+</head>
+<body>
+  <main>
+    <h1>Sample HTML Page</h1>
+    <p>This page shows <strong>basic conversion</strong> to Markdown.</p>
+    <h2>Links and Lists</h2>
+    <p>Visit <a href="https://example.com">Example</a>.</p>
+    <ul>
+      <li>Headings</li>
+      <li>Paragraphs</li>
+      <li>Links</li>
+    </ul>
+    <pre><code>console.log("hello markdown");</code></pre>
+  </main>
+</body>
+</html>

examples/sample.md

@@ -0,0 +1,15 @@
+# Sample HTML Page
+
+This page shows **basic conversion** to Markdown.
+
+## Links and Lists
+
+Visit [Example](https://example.com).
+
+- Headings
+- Paragraphs
+- Links
+
+```text
+console.log("hello markdown");
+```

html2md

@@ -0,0 +1,2 @@
+#!/usr/bin/env sh
+python3 "$(dirname "$0")/html2md.py" "$@"