@xz-summer/milkdown-container

Milkdown 编辑器的容器指令插件，支持多种容器类型，可自定义配置。

特性

- 🎨 7 种内置容器类型（important、info、note、tip、warning、caution、details）
- 🔧 完全可配置（标题、图标、别名）
- 🌙 支持亮色/暗色主题
- ⌨️ 快捷输入支持
- 📦 可折叠的 details 容器

安装

``bash
pnpm add @xz-summer/milkdown-container
`

基本使用

`typescript
import { Editor } from "@milkdown/kit/core";
import { commonmark } from "@milkdown/kit/preset/commonmark";
import { containerPlugin } from "@xz-summer/milkdown-container";
import "@xz-summer/milkdown-container/style.css";

const editor = await Editor.make()
.use(commonmark)
.use(containerPlugin)
.create();
`

Markdown 语法

`markdown
:::info[信息标题]
这是一个信息容器
:::

:::tip[提示]
这是一个提示容器
:::

:::warning[警告]
这是一个警告容器
:::

:::caution[危险]
这是一个危险容器
:::

:::details[点击展开]
这是一个可折叠容器
:::
`

内置容器类型

| 类型 | 别名 | 默认标题 | 颜色 |
|------|------|----------|------|
| important | - | 重要 | 紫色 |
| info | default | 信息 | 蓝色 |
| note | - | 注意 | 灰色 |
| tip | tips, hint | 提示 | 绿色 |
| warning | warn | 警告 | 黄色 |
| caution | danger, error | 危险 | 红色 |
| details | detail, collapse, collapsible | 详情 | 靛蓝色 |

快捷输入

在编辑器中输入以下内容后按 Enter 即可创建容器：

`
:::info
:::info[自定义标题]
:::tip
:::warning
:::details[详情]
`

自定义属性

支持添加自定义 class、id 和其他属性：

`markdown
:::info[标题]{.custom-class #my-id data-custom="value"}
内容
:::
`

自定义配置

使用 ctx.update 配合 mergeContainerConfig 在 .config() 中配置：

`typescript
import {
containerPlugin,
containerConfig,
mergeContainerConfig,
ContainerTypes,
infoIcon,
} from "@xz-summer/milkdown-container";

// 自定义 SVG 图标
const successIcon = ;

const editor = await Editor.make()
.use(commonmark)
.use(containerPlugin)
.config((ctx) => {
ctx.update(containerConfig.key, mergeContainerConfig({
types: [
// 覆盖现有类型
{
type: ContainerTypes.INFO,
title: "Info",
icon: infoIcon,
aliases: ["information", "default"]
},
// 添加新类型
{
type: "success",
title: "成功",
icon: successIcon,
aliases: ["ok", "done"]
},
]
}));
})
.create();
`

$3

`typescript
interface ContainerTypeConfig {
/* 容器类型标识（必填） /
type: string;
/* 默认标题 /
title: string;
/* 图标 SVG 字符串 /
icon: string;
/* 别名列表（可选） /
aliases?: string[];
}

interface ContainerConfig {
/* 自定义容器类型配置（会与默认配置合并） /
types: ContainerTypeConfig[];
}
`

$3

`typescript
import { ContainerTypes } from "@xz-summer/milkdown-container";

ContainerTypes.IMPORTANT // "important"
ContainerTypes.INFO // "info"
ContainerTypes.NOTE // "note"
ContainerTypes.TIP // "tip"
ContainerTypes.WARNING // "warning"
ContainerTypes.CAUTION // "caution"
ContainerTypes.DETAILS // "details"
`

$3

`typescript
import {
containerConfig,
mergeContainerConfig,
ContainerTypes
} from "@xz-summer/milkdown-container";

const customDetailsIcon = ;

ctx.update(containerConfig.key, mergeContainerConfig({
types: [
{
type: ContainerTypes.DETAILS,
title: "Click to expand",
icon: customDetailsIcon,
aliases: ["detail", "collapse", "collapsible", "spoiler"],
}
]
}));
`

$3

新增容器类型需要添加对应的 CSS 样式：

`css
/ 新增 success 类型样式 /
.milkdown-container.success {
background-color: var(--xz-c-green-soft);
}

.milkdown-container.success .milkdown-container-title {
color: var(--xz-c-green-text);
}
`

主题支持

插件内置了亮色和暗色主题支持。通过 data-theme="dark" 属性切换：

`html

`

$3

`css
:root {
/ 灰色系 /
--xz-c-grey-text: #656869;
--xz-c-grey-soft: rgb(142 150 170 / 14%);

/ 蓝色系 /
--xz-c-blue-text: #2888a7;
--xz-c-blue-soft: rgb(27 178 229 / 14%);

/ 绿色系 /
--xz-c-green-text: #18794e;
--xz-c-green-soft: rgb(16 185 129 / 14%);

/ 黄色系 /
--xz-c-yellow-text: #915930;
--xz-c-yellow-soft: rgb(234 179 8 / 14%);

/ 红色系 /
--xz-c-red-text: #b8272c;
--xz-c-red-soft: rgb(244 63 94 / 14%);

/ 紫色系 /
--xz-c-purple-text: #6f42c1;
--xz-c-purple-soft: rgb(159 122 234 / 14%);

/ 靛蓝色系 /
--xz-c-indigo-text: #3451b2;
--xz-c-indigo-soft: rgb(100 108 255 / 14%);
}
`

架构说明

$3

details 容器使用独立的 Schema 实现，与普通容器分离。原因：

- HTML

元素要求

作为第一个子元素
- 普通容器使用

结构
- 如果共用 Schema，会导致 DOM 结构不符合 HTML 规范，浏览器原生折叠功能失效

`
普通容器结构：

标题

内容

Details 结构：

标题

内容

`

斜杠菜单集成

插件导出了预配置的斜杠菜单项，可直接用于斜杠菜单插件：

$3

`typescript
import { containerSlashMenuGroup } from '@xz-summer/milkdown-container'
import { menuRegistryCtx } from '@xz-summer/milkdown-slash-menu-vue'

editor.config((ctx) => {
const registry = ctx.get(menuRegistryCtx.key)
registry.registerGroup(containerSlashMenuGroup)
})
`

$3

`typescript
import { containerSlashMenuItems } from '@xz-summer/milkdown-container'
import { menuRegistryCtx, DEFAULT_GROUP_IDS } from '@xz-summer/milkdown-slash-menu-vue'

editor.config((ctx) => {
const registry = ctx.get(menuRegistryCtx.key)
// 只注册部分容器类型
registry.registerItem(DEFAULT_GROUP_IDS.ADVANCED, containerSlashMenuItems.info)
registry.registerItem(DEFAULT_GROUP_IDS.ADVANCED, containerSlashMenuItems.tip)
})
`

$3

`typescript
import { containerSlashMenuItems } from '@xz-summer/milkdown-container'

registry.registerGroup({
id: 'my-containers',
label: '我的容器',
layout: 'list',
items: [
{ ...containerSlashMenuItems.info, label: '信息提示' },
{ ...containerSlashMenuItems.warning, label: '警告信息' },
],
})
`

API 参考

$3

`typescript
// 插件
export { containerPlugin }; // 插件数组
export { remarkDirective }; // Remark 指令插件

// 配置
export { containerConfig }; // 配置 slice
export { mergeContainerConfig }; // 合并配置工具函数
export { defaultContainerTypes }; // 默认容器类型配置
export { ContainerTypes }; // 类型常量

// 普通容器 Schema
export { containerSchema };
export { containerTitleSchema };
export { containerContentSchema };
export { containerTitleNodeView };

// Details Schema
export { detailsSchema };
export { detailsSummarySchema };
export { detailsContentSchema };
export { detailsNodeView };
export { detailsSummaryNodeView };

// 通用
export { containerKeymap };
export { containerDropPlugin };
export { createContainerCommand };

// 工具函数
export { getContainerConfig };
export { getContainerIcon };
export { getDefaultTitle };
export { getDetailsConfig };

// 图标
export {
importantIcon,
infoIcon,
noteIcon,
tipIcon,
warningIcon,
cautionIcon,
detailsIcon,
};

// 斜杠菜单配置
export { containerSlashMenuItems }; // 单个菜单项配置
export { containerSlashMenuGroup }; // 完整分组配置

// 类型
export type { ContainerTypeConfig };
export type { ContainerConfig };
`

$3

`typescript
import { createContainerCommand } from "@xz-summer/milkdown-container";
import { commandsCtx } from "@milkdown/kit/core";

editor.action((ctx) => {
ctx.get(commandsCtx).call(createContainerCommand.key, "info", "自定义标题");
});
``

许可证

MIT

Show more