Container directive plugin for Milkdown - supports info, tip, warning, danger, and details containers | Milkdown 容器指令插件 - 支持信息、提示、警告、危险和详情容器
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", "自定义标题");
});
``