快速开始

先照着这条最短路径跑一遍：安装 MagicMD，打开本地 Studio 控制台，粘贴一篇公开文章链接，然后在界面里查看生成的 Markdown 内容包。跑通之后，再开启批量转换、自定义输出规则和 GitHub 发布。

1. 安装 MagicMD

推荐用 uv 安装，它会把命令行工具隔离到独立环境里：

uv tool install magicmd
magicmd doctor

magicmd doctor 用来检查本机环境和常见依赖。如果这一步通过，后面的转换命令就可以直接跑。

其他安装方式

如果你习惯 pipx：

pipx install magicmd
magicmd doctor

npm 包是一个轻量入口，底层会调用 PyPI 版 MagicMD CLI：

npm install -g magicmd
magicmd doctor

2. 打开本地 Studio

对新手用户，推荐先用本地网页控制台：

magicmd studio

浏览器会打开：

http://127.0.0.1:8765

在 Studio 里粘贴文章链接，点击“转换 Markdown”，右侧会显示生成目录、文件列表和需要复查的提示。更多说明见 MagicMD Studio。

3. 用命令行转换第一篇文章

复制一条公开文章链接，直接交给 MagicMD。它会自动提取正文、清理代码块、处理媒体资源和来源信息：

magicmd "https://mp.weixin.qq.com/s/example"

也可以显式指定输出目录：

magicmd convert "https://juejin.cn/post/example" -o output/

4. 打开生成结果

默认会生成一个内容包目录：

output/article-title/
├── article.md
├── metadata.json
├── extraction-report.json
└── images/
    ├── img_001.png
    └── img_002.png

article.md 是深度清理后的正文，metadata.json 是文章元信息，extraction-report.json 是转换报告。报告里会记录 warning、媒体下载结果和需要人工复核的地方。

5. 批量转换

把要转换的链接放进 urls.txt，一次性批量生成内容包：

https://mp.weixin.qq.com/s/example
https://juejin.cn/post/example
https://blog.csdn.net/user/article/details/123

运行批量任务：

magicmd batch urls.txt -o output/

断点续跑时可以跳过已经存在的内容包：

magicmd batch urls.txt -o output/ --skip-existing

6. 使用配置文件

如果你要把文章发布到 Hugo、Docusaurus 或自己的知识库，建议先生成一份配置，自定义目录、文件名、metadata 和媒体路径：

cp .magicmd.example.toml .magicmd.toml
magicmd "https://mp.weixin.qq.com/s/example" --config .magicmd.toml

也可以直接用 配置生成器 选择发布目标、文件命名和媒体路径，再把生成的 .magicmd.toml 放到项目根目录。

7. 发布到 GitHub 内容仓库

这一功能适合把转换结果提交到 Hugo、Docusaurus、博客或知识库的 GitHub 内容仓库。推荐先用 配置生成器 生成 .magicmd.toml，勾选“生成 GitHub 发布配置”，把目标仓库和目录固定下来。完整流程见 发布到 GitHub 内容仓库。

配置好之后，先用 dry-run 查看 MagicMD 会写入哪些文件：

magicmd publish github "https://mp.weixin.qq.com/s/example" --dry-run

确认目标仓库、分支、目录和文件列表后，再执行实际发布：

GITHUB_TOKEN=ghp_xxx

magicmd publish github "https://mp.weixin.qq.com/s/example" --pr

真实发布需要 GITHUB_TOKEN。推荐把它放在项目根目录的 .env，MagicMD 会自动读取；dry-run 不需要 token，也不会创建分支、提交、push 或 Pull Request。如果 dry-run 里标题还是 URL、目录出现 undated，或者文件列表包含 debug.html，先查看 GitHub 发布教程的排查说明，不要急着真实发布。

8. 在程序里调用

如果你要把 MagicMD 接入自己的 Python 后端、CMS、HaoGit 或定时任务，不需要解析 CLI 输出。直接使用 SDK 接入，调用 from magicmd import convert_article，拿到结构化的 Markdown、metadata、图片和转换报告。