article2md

article2md

English | 简体中文

Turn any web article — including WeChat, Zhihu, and Xiaohongshu posts behind login walls — into clean, semantic Markdown with locally saved images. Built for Obsidian-style knowledge bases and LLM workflows, and it runs entirely on your machine.

Why article2md

• Login-wall Chinese platforms. WeChat Official Account, Zhihu, and Xiaohongshu articles get deleted or expire all the time. article2md archives them through your own logged-in browser session — no password stored, nothing sent to a cloud.
• Images live next to your notes. Every image is downloaded into a local assets/ folder with stable names, so your archive never shows broken images when a CDN link dies.
• Made for knowledge bases. index.md starts with YAML front matter (title, source, author, saved, …) that Obsidian and Logseq understand out of the box.
• Made for LLM pipelines. --stdout prints clean Markdown for piping into any AI CLI or script.
• Quality you can trust. Every archive gets a quality grade plus a manifest.json; anything suspicious also gets a diagnostics.json for review.

Quick start

npm install -g article2md
npx playwright install chromium   # one-time browser download

article2md save "https://www.anthropic.com/engineering/building-effective-agents"

Already copied a link? Just run:

article2md save

Prefer a local web UI?

article2md ui

How it compares

	article2md	Browser clipper extensions	Cloud URL→Markdown services
WeChat / Zhihu / Xiaohongshu behind login	Yes, with your own session	Partial	No
Images downloaded locally	Yes, stable assets/ names	Varies	No, remote links
Batch archiving	Yes	No	Yes
Privacy	Fully local	Local	Pages sent to a cloud
Quality report	Manifest + diagnostics	No	No

Usage

# Save a single article (directory per article)
article2md save "https://example.com/article" --out ~/notes/articles

# Save the URL currently on your clipboard
article2md save

# Print Markdown to stdout (no files written; great for piping into LLM tools)
article2md save "https://example.com/article" --stdout

# Batch save a list of URLs
article2md batch urls.txt --out ~/notes/articles --skip-existing

# Local web UI
article2md ui --port 4312

Common options:

-o, --out <directory>     Output directory. Defaults to "articles".
--stdout                  Print Markdown to stdout instead of writing files (save only).
--no-front-matter         Skip the YAML front matter block.
--force                   Overwrite an existing article directory.
--skip-existing           Skip when the article directory already exists.
--dry-run                 Show the planned output path without writing files.
--image-retries <count>   Retry failed image downloads. Defaults to 1.
--image-timeout-ms <ms>   Image download timeout. Defaults to 15000.

URL list format for batch:

# Blank lines and full-line comments are ignored.
https://www.anthropic.com/research/building-effective-agents
https://openai.com/research/
https://example.com/article#section

Use with AI agents (MCP)

article2md ships an MCP server, so agents like Cursor, Claude Code, and Claude Desktop can archive articles for you mid-conversation — "save this article to my knowledge base" just works.

Add it to your MCP config (e.g. ~/.cursor/mcp.json or Claude Desktop's claude_desktop_config.json):

{
  "mcpServers": {
    "article2md": {
      "command": "npx",
      "args": ["-y", "article2md", "mcp", "--out", "/absolute/path/to/your/articles"]
    }
  }
}

If article2md is installed globally, "command": "article2md", "args": ["mcp", "--out", "..."] works too.

Exposed tools:

• save_article — archive a URL as Markdown with local images into your articles directory
• read_article — return an article as clean Markdown text without writing files
• auth_status — check which login sessions (zhihu / weixin / xiaohongshu) are saved

--out sets the default output directory (~ is expanded); the agent can override it per call. Logging in for walled sources still happens in your terminal: article2md auth login <profile>.

Output

Each article becomes a folder. Titles with Chinese characters keep them in the folder name; English-only titles use ASCII slugs.

articles/
  building-effective-agents/
    index.md          # Markdown with YAML front matter
    manifest.json     # metadata, quality grade, image list
    diagnostics.json  # written only when the archive needs review
    original.html     # rendered page snapshot
    preview.html      # local preview with images
    assets/
      001-diagram-a1b2c3.png

index.md starts with front matter your note tools can index:

---
title: "Building effective agents"
source: "https://www.anthropic.com/engineering/building-effective-agents"
site: "Anthropic"
saved: "2026-08-12T15:46:18.177Z"
quality: "exact-ish"
---

Disable it with --no-front-matter or "frontMatter": false in the config file.

batch-report.json records per-URL status: success, skipped, dry-run, or failed (a failed URL never stops the rest of the batch).

Fixed sources

article2md recognizes these sources and applies dedicated extraction rules; every other public page goes through the generic article extractor:

Anthropic, OpenAI, Google DeepMind, Google Research, Hugging Face, Microsoft Research, Berkeley AI Research, Lilian Weng, Chip Huyen, Simon Willison, Jiqizhixin (机器之心), QbitAI (量子位), Zhihu (知乎), WeChat Official Accounts (微信公众号), Xiaohongshu (小红书), Medium, Substack.

Want another site to work great? Request a source adapter or add one yourself — see CONTRIBUTING.md.

It intentionally drops page chrome: navigation, ads, footers, recommendations, popups, and comments.

Session login (Zhihu, WeChat, Xiaohongshu, Medium, Substack)

Some articles require a logged-in browser session — Zhihu login walls, WeChat verification, Xiaohongshu notes, Medium member-only stories, Substack paid posts, or sites that challenge automated browsers. Log in once in a headed Chromium window; archive commands then reuse the saved Playwright storageState:

article2md auth login zhihu        # or weixin / xiaohongshu / medium / substack
article2md auth status
article2md auth logout all

Sessions are stored per profile under ~/.article2md/sessions/ (override with ARTICLE2MD_SESSIONS_DIR). They contain cookies — never commit them.

Configuration

Copy article2md.config.example.json to article2md.config.json to set local defaults:

{
  "out": "articles",
  "skipExisting": false,
  "force": false,
  "dryRun": false,
  "frontMatter": true,
  "imageRetries": 1,
  "imageTimeoutMs": 15000
}

Install from source

git clone https://github.com/tzrea1-Q/article2md.git
cd article2md
npm install
npx playwright install chromium
node ./src/index.js save "https://example.com/article"

Quality grades

• exact-ish: fixed source matched and passed semantic checks
• good: generic extraction passed semantic checks
• needs-review: extraction succeeded, but warnings suggest a manual check
• failed: reserved for future recoverable-failure reports

Roadmap

Highlights (see ROADMAP.md for details):

• Medium / Substack adapters
• Single-file export and clipboard watch mode
• RSS/Atom feed input for batch archiving

Contributing

• Run npm test before opening a PR
• Behavior changes need new or updated tests
• Keep changes focused so they are easy to review
• Missing Chromium locally? Run npx playwright install chromium

Security boundaries

This tool archives pages you can already open in your browser. Zhihu, WeChat, and Xiaohongshu support reuses a local Playwright storageState saved after you log in manually.

Allowed	Not allowed
You log in manually; the tool persists and reuses storageState	Storing passwords or auto-filling credentials
Archiving pages your account can already view	Defeating captchas, paywalls, or anti-bot systems
Session files stay in your local profile directory	Sharing/committing session files; mixing cookies across sites

Report security issues privately through GitHub Security Advisories first.

License

MIT