Atom编辑器已停止维护，markdown-toc插件在1.60+版本中不可用，主因是atom.io下线及Electron升级导致API失效；推荐切换至VS Code+Markdown All in One插件，或使用mdtoc命令行工具生成目录。
Atom 编辑器已停止维护（2022年12月15日官方终止支持），markdown-toc 插件在当前 Atom 版本（1.60+）中基本不可用，强行安装会报错或无法生成目录。
如果你仍在使用 Atom，唯一可行的路径是降级到旧版 + 手动适配，但不推荐。更务实的做法是切换工具链——下面直接说清楚「怎么换、换什么、为什么必须换」。
Atom 里装不了 markdown-toc 的真实原因
插件仓库 atom.io 已下线，apm install markdown-toc 会返回 ENOTFOUND 或 404；即使从 GitHub 拉源码手动安装，也会因 Electron 升级（Atom 1.58+ 基于 Electron 13+）导致 atom-text-editor API 失效，getBuffer() 和 scan() 调用失败，插件根本读不到文档标题。
替代方案：用 VS Code + Markdown All in One 替代
这是目前最接近 Atom 体验、且稳定支持 TOC 的组合：
Xlsx To Markdown
下载
文档转 Markdown 转换器 - 将 DOCX、PPTX、Excel 文件转换为 Markdown。用于从 Word 文档、PowerPoint 演示文稿或 E... 提取内容。
- 安装
Markdown All in One插件（ID：yzane.markdown-all-in-one） - 打开 Markdown 文件，光标放在想插入目录的位置
- 按
Ctrl+Shift+P→ 输入Insert Table of Contents→ 回车 - 默认生成无序链接列表，如需编号，修改设置：
"markdown.extension.toc.orderedList": true - 保存文件后，目录会自动更新（需开启
"markdown.extension.toc.updateOnSave": true）
命令行 fallback：用 mdtoc 本地生成
适合 CI/CD 或批量处理，不依赖编辑器：
- 全局安装：
npm install -g mdtoc - 在 Markdown 文件里加占位符：
<!-- toc --> - 执行：
mdtoc -i README.md - 注意：
mdtoc默认只解析#到###（三级），如需包含四级标题，加参数：-d 4 - 生成的锚点格式兼容 GitHub（
github.comanchor mode），但不兼容 Obsidian 的^式块引用
别踩坑：手动写目录时锚点命名规则
自动生成失败时，手动补目录最容易出错的是链接目标不匹配：
- 标题
## 数据预处理步骤→ 锚点是#数据预处理步骤（全小写、空格变短横、中文保留） - 标题含符号如
### API: get_user(id)→ 实际锚点是#api-get_userid（冒号、括号被丢弃） - GitHub 渲染器会自动标准化，但本地预览（如 Typora）可能不一致，建议用
[API: get_user(id)](#api-get_userid)显式写死 - 避免用
[TOC]或@[toc]—— Atom 不识别，VS Code 默认也不处理，仅 Typora/Obsidian 支持
Atom 的 TOC 生态已经断掉，硬扛只会浪费调试时间。真正省事的方式是换到 VS Code，或者用 mdtoc 命令行兜底——后者甚至能塞进 pre-commit 钩子里，一劳永逸。
