webtomd 0.1.1

Web to Markdown. No garbage.

webtomd

Web to Markdown. No garbage.

A fast, terminal-native CLI that converts any URL into clean, structured Markdown. Supports multi-provider AI post-processing, batch conversion, CSS selectors, and YAML frontmatter — all from one command.

Works on Windows, macOS, and Linux. Python 3.11+.

Quick Start

pip install webtomd
webtomd https://example.com/article

That's it. The Markdown file is saved in your current directory.

Install

pip (all platforms)

pip install webtomd

uv (recommended — faster)

uv pip install webtomd

pipx (isolated global install)

pipx install webtomd

Optional extras

# AI provider support
pip install "webtomd[openai]"
pip install "webtomd[anthropic]"
pip install "webtomd[gemini]"
pip install "webtomd[groq]"
pip install "webtomd[ai-all]"

# JS-rendered page support (SPAs, React/Vue/Next.js sites)
pip install "webtomd[playwright]"
playwright install chromium

Verify installation

webtomd --help

If webtomd isn't found in your PATH, you can always run it as a module:

python -m webtomd --help

Features

• Smart extraction — trafilatura + readability fallback chain with quality scoring
• JS-rendered pages — optional Playwright fallback for SPAs
• AI modes — summarize, translate, extract, Q&A via Anthropic / OpenAI / Gemini / Groq / Ollama
• Batch processing — convert a file of URLs in one command with progress bar
• CSS selectors — target specific page sections
• YAML frontmatter — title, URL, date metadata
• Auto-save — interactive terminals save files; piped runs output to stdout
• Smart filenames — deterministic or AI-assisted naming
• Clipboard — copy output with --copy
• stdin support — pipe HTML directly
• Recursive crawl — --depth N discovers and converts same-domain linked pages
• Clean output — strips nav, sidebars, cookie banners, CSS noise, duplicate content
• Cross-platform — Windows, macOS, Linux with encoding-safe output

Usage

Basic conversion

# Auto-saves .md file in interactive terminals
webtomd https://example.com/article

# Save to a specific file
webtomd https://example.com/article -o article.md

# Force output to terminal
webtomd https://example.com/article --stdout

Selectors and metadata

# Extract only content inside a CSS selector
webtomd https://example.com --selector "main"
webtomd https://example.com --selector "article .content"

# Add YAML frontmatter (title, url, date)
webtomd https://example.com --metadata

AI post-processing

webtomd https://example.com --ai summarize
webtomd https://example.com --ai "tl;dr"
webtomd https://example.com --ai translate
webtomd https://example.com --ai extract
webtomd https://example.com --ai qa

Batch and crawl

# Batch: convert a list of URLs
webtomd --batch urls.txt

# Crawl: recursively discover and convert same-domain links
webtomd https://example.com --depth 2

Stdin (pipe HTML directly)

macOS / Linux:

curl -s https://example.com | webtomd - --stdout
curl -s https://example.com | webtomd --stdout

Windows (PowerShell):

(Invoke-WebRequest https://example.com).Content | python -m webtomd - --stdout

Other options

# Copy result to clipboard
webtomd https://example.com --copy

# Open in default editor after saving
webtomd https://example.com --open

# Silent mode (no spinners, no preview — pipe-safe)
webtomd https://example.com --silent -o out.md

# Filename strategy
webtomd https://example.com --name-strategy deterministic
webtomd https://example.com --name-strategy ai

AI Setup

Set your provider's API key as an environment variable.

macOS / Linux (bash/zsh):

export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
export GEMINI_API_KEY=...
export GROQ_API_KEY=gsk_...
export OLLAMA_HOST=http://localhost:11434

Windows (PowerShell):

$env:OPENAI_API_KEY = "sk-..."
$env:ANTHROPIC_API_KEY = "sk-ant-..."
$env:GEMINI_API_KEY = "..."
$env:GROQ_API_KEY = "gsk_..."
$env:OLLAMA_HOST = "http://localhost:11434"

Windows (Command Prompt):

set OPENAI_API_KEY=sk-...
set ANTHROPIC_API_KEY=sk-ant-...

To persist across sessions, add these to your shell profile (~/.bashrc, ~/.zshrc) or set them via Windows System Environment Variables.

Or use the interactive setup wizard (writes to ~/.webtomdrc):

webtomd --configure

The first available key is auto-detected in priority order: Anthropic > OpenAI > Gemini > Groq > Ollama.

If no key is configured, --ai modes gracefully fall back to plain Markdown output with a friendly message — nothing breaks.

Configuration

Create ~/.webtomdrc (TOML format) for persistent defaults:

output_dir = "~/Documents/webtomd"
copy = false
metadata = false
silent = false
name_strategy = "deterministic"
ai_provider = "openai"

CLI flags always override config file values.

Location: ~/.webtomdrc resolves to:

• macOS/Linux: /home/yourname/.webtomdrc
• Windows: C:\Users\YourName\.webtomdrc

Batch Mode

Create a text file with one URL per line (# comments supported):

# My reading list
https://example.com/article-1
https://example.com/article-2
https://example.com/article-3

webtomd --batch urls.txt

Each URL is processed independently with a live progress bar — failures don't abort the batch. A summary is printed at the end.

Output Defaults

Context	Behavior
Interactive terminal	Auto-saves .md file with generated name
Piped / non-interactive	Prints Markdown to stdout
-o file.md	Saves to the specified file
--stdout	Forces stdout in any context

Troubleshooting

webtomd command not found:

• Ensure your Python Scripts (Windows) or bin (macOS/Linux) directory is in your PATH
• Alternative: python -m webtomd

Encoding errors on Windows:

• webtomd handles UTF-8 output automatically, but if your terminal shows garbled characters, run chcp 65001 first or use Windows Terminal (recommended over cmd.exe)

Playwright not installing:

• Run playwright install chromium after installing the playwright extra
• On Linux, you may need system deps: playwright install-deps chromium

Clipboard not working:

• macOS: works out of the box (pbcopy)
• Linux: install xclip or xsel (sudo apt install xclip)
• Windows: works out of the box

Slow conversion on certain sites:

• Some sites throttle or block automated requests — this is network-bound, not a tool issue
• Try --selector "main" to skip heavy page processing

Contributing

git clone https://github.com/MrRaccooon/WebToMD.git
cd WebToMD

Setup (all platforms):

pip install uv         # if you don't have uv
uv sync --extra dev
uv run pytest

Run lints:

uv run ruff check .

Run type checks:

uv run mypy webtomd/

License

GPL-3.0-or-later