Milkdown 嵌套列表缩进配置指南：indent 插件使用与 indentConfig 参数详解

Milkdown 嵌套列表缩进配置指南：indent 插件使用与 indentConfig 参数详解

【免费下载链接】milkdown🍼 Plugin driven WYSIWYG markdown editor framework.项目地址: https://gitcode.com/GitHub_Trending/mi/milkdown

写 Markdown 时经常要处理嵌套列表、任务清单这类有层级的内容，缩进处理不好，排出来的层级就容易乱。Milkdown 里的缩进能力由@milkdown/plugin-indent提供，一个 Tab 键就能在光标处插入缩进字符，配合indentConfig配置项还能把缩进单位换成团队规范里要求的空格数或制表符。

两步接入：在编辑器里启用 indent 插件

如果你只想快速跑起来，只需要做这两步：导入插件、挂载到编辑器。

import { Editor } from '@milkdown/core' import { indent, indentConfig } from '@milkdown/plugin-indent' Editor .make() .use(indent) // 挂上后 Tab 键即可插入缩进 .create()

默认配置通常够用：type为'space'、size为2，也就是每次按 Tab 插入两个空格。

这里的关键是配置项，而不是插件本身——indent只是一个把 Tab 键接到缩进逻辑上的快捷键，真正决定插入什么、插入多少的是indentConfig。

indentConfig 参数说明：type 与 size 怎么填

想改缩进行为，在初始化时通过.config()写入即可：

.config(ctx => { ctx.set(indentConfig.key, { type: 'space', // 用空格做缩进；填 'tab' 则每次插入一个制表符 size: 4, // 每次按 Tab 插入的空格数 }) })

一个容易踩的点：type设为'tab'时，插入的固定是一个制表符，size对制表符不生效。如果你的团队规范要求 4 空格，就保持type: 'space'并把size调到 4。

顺带一提，Milkdown 官方的高层封装 Crepe 内置了 indent 插件，并把size覆盖成了 4，见 packages/crepe/src/core/builder.ts。用 Crepe 时你不需要手动挂载，但想知道它的缩进行为，可以顺着这份源码确认。

什么时候会触发，什么时候不会

Tab 触发的缩进有明确前提，理解这两条能少查很多错：

• 光标必须停在可编辑文本里。选中状态是普通文本选区（TextSelection）或全选（AllSelection）时才会插入，选在别的节点上（比如图片、表格）则什么都不发生。
• 插入位置就是光标所在位置，它把字符串直接写进文档，序列化出的 Markdown 就是带缩进的前导空格。

所以想给一组任务清单做层级，常见做法是：把光标放到子项行首，按 Tab 让前导空格对齐，再录入内容。层级建议控制在 3 级以内，再深的内容用标题或表格组织更清晰。

和"列表自动重排"的区别

这是新手最常被误导的地方：indent插件是插入缩进字符，不是给列表项做层级升降的"自动缩进命令"。列表项的嵌套结构，主要由你在 ProseMirror 文档里的节点层级决定，而不是这个快捷键直接改出来的。

如果你希望"选中列表项按 Tab 就整体下沉一级"这类行为，需要借助 keymap 或 slash 命令另行实现；而代码块里的 Tab 缩进则是另一套机制——Crepe 的代码块基于 CodeMirror，用的是indentWithTab，配置入口在 packages/crepe/src/feature/code-mirror/index.ts，和正文的 indent 插件互不干扰。

Tab 没有反应的排查思路

• 现象：按 Tab 完全没变化→ 通常没挂载插件。确认Editor.make()链上执行过.use(indent)，或用 Crepe 时检查features是否被禁用。
• 现象：每次插入的字符数不对→ 大概率是indentConfig没写进去，或在插件之前被其他配置覆盖。可以用ctx.get(indentConfig.key)打印当前值核对。
• 现象：光标在表格或图片上按 Tab 无效→ 这是预期行为，选区类型不满足触发条件，把光标移回文本行再试。

参数定义和默认值都在 packages/plugins/plugin-indent/src/index.ts，接口文档在 docs/api/plugin-indent.md，不确定某个行为时直接对照这两处最快。

下一步

先把size和团队文档规范对齐（比如统一 4 空格），再验证一次 Tab 的实际输出。如果后续需要"列表项整体升降级"或代码块内的自定义缩进键位，再去找 keymap 相关的扩展点，不必动 indent 插件本身。

【免费下载链接】milkdown🍼 Plugin driven WYSIWYG markdown editor framework.项目地址: https://gitcode.com/GitHub_Trending/mi/milkdown