wxarticle2md

wxarticle2md is a WeChat public account article exporter. It can save an article as MHTML, convert it to basic Markdown, or use a rendered browser snapshot plus an LLM to produce polished Markdown.

Features

• Export a single WeChat article to MHTML.
• Export basic Markdown with local images.
• Export advanced Markdown with browser-rendered page capture and LLM restructuring.
• Normalize downloaded media: static images to JPEG, animations to GIF, video to MP4, and audio to MP3.
• Use advanced-lite for clean final output: one Markdown file plus assets/.
• Use advanced-lite-zip for the same deliverables packaged as one .md.zip file.
• Batch export from CSV with bounded concurrency, resume support, and per-URL status.
• Write per-URL status to batch_report.json.

Install

For local development:

uv sync

Run the CLI from the project:

uv run wxarticle2md --help

Install as a local CLI tool:

uv tool install -e .
wxarticle2md --help

If you use the Playwright backend, install its browser runtime:

uv run python -m playwright install chromium

The default browser backend is Camoufox. If Camoufox fails during launch, context creation, page creation, navigation, or capture, the exporter falls back to Playwright automatically.

Environment

Advanced Markdown modes require an OpenAI-compatible LLM API. Create a local .env:

OPENAI_API_KEY=your_api_key
LLM_MODEL=your_model_name
OPENAI_BASE_URL=https://api.openai.com

OPENAI_BASE_URL can stay as-is for the official OpenAI API. Change it only when using another OpenAI-compatible provider.

Single Article

Export MHTML:

uv run wxarticle2md "https://mp.weixin.qq.com/s/..." --format mhtml

Export basic Markdown:

uv run wxarticle2md "https://mp.weixin.qq.com/s/..." --format md

Export advanced Markdown with debug artifacts:

uv run wxarticle2md "https://mp.weixin.qq.com/s/..." --format md --md-mode advanced

Export clean advanced Markdown:

uv run wxarticle2md "https://mp.weixin.qq.com/s/..." --format md --md-mode advanced-lite

Export clean advanced Markdown as a ZIP package:

uv run wxarticle2md "https://mp.weixin.qq.com/s/..." --format md --md-mode advanced-lite-zip

Useful advanced options:

uv run wxarticle2md "https://mp.weixin.qq.com/s/..." `
  --format md `
  --md-mode advanced-lite `
  --browser camoufox `
  --model gpt-4.1-mini `
  --max-media 200 `
  --no-video

Advanced Modes

advanced keeps debug artifacts:

output/
  article-title-urlhash/
    document.md
    assets/
    manifest.json
    source.html
    page_snapshot.json
    llm_input.txt
    llm_output.raw.md

advanced-lite keeps only final deliverables:

output/
  article-title-urlhash/
    article-title.md
    assets/

advanced-lite-zip packages those deliverables without an extra top-level folder:

output/
  article-title-urlhash.md.zip

Archive contents:

article-title.md
assets/
manifest.min.json

The URL hash suffix prevents collisions when different articles have the same title.

Batch Export

Batch mode reads a CSV file and keeps up to --concurrency articles running at the same time. When one article finishes, the next URL starts immediately; it does not wait for a fixed batch of N articles to finish.

CSV can be one URL per row:

https://mp.weixin.qq.com/s/xxx
https://mp.weixin.qq.com/s/yyy

Or a CSV with a url column:

url
https://mp.weixin.qq.com/s/xxx
https://mp.weixin.qq.com/s/yyy

Run:

uv run wxarticle2md `
  --input urls.csv `
  --format md `
  --md-mode advanced-lite `
  --concurrency 3

Resume an interrupted batch and skip URLs that already completed successfully:

uv run wxarticle2md `
  --input urls.csv `
  --format md `
  --md-mode advanced-lite `
  --concurrency 3 `
  --resume

Force re-export of every URL:

uv run wxarticle2md `
  --input urls.csv `
  --format md `
  --md-mode advanced-lite `
  --force

Batch mode rules:

• --input requires --md-mode advanced, advanced-lite, or advanced-lite-zip.
• --input requires --format md.
• Each URL writes one independent output folder.
• --resume reads batch_report.json, marks stale running rows as interrupted, and skips successful rows whose Markdown or .md.zip package still exists.
• --force disables resume skipping and reprocesses every URL.
• A failed URL is recorded and does not stop the rest of the queue.
• Results are written atomically to output/batch_report.json.

Entrypoints

The canonical command is:

uv run wxarticle2md --help

The root script entrypoint is also available:

uv run python wxarticle2md.py --help

Notes

• .env, .venv/, and output/ are ignored by Git.
• Media formats are detected from their actual contents and transcoded; changing only the filename extension is never used as a substitute for conversion.
• Basic Markdown downloads article images. Advanced modes additionally download direct video and audio sources; embedded players that do not expose a direct media URL are retained as metadata.
• On Windows, if a terminal has encoding trouble, set:

$env:PYTHONIOENCODING='utf-8'

Acknowledgements

Thanks to jackwener/wechat-article-to-markdown. This project builds in the same problem space and takes inspiration from the idea of making WeChat article export practical and scriptable.