@xz-summer/milkdown-container

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

特性

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

安装

pnpm add @xz-summer/milkdown-container

基本使用

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 语法

:::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 和其他属性：

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

自定义配置

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

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

// 自定义 SVG 图标
const successIcon = `<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='currentColor'><path d='M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2zm-2 15l-5-5 1.41-1.41L10 14.17l7.59-7.59L19 8l-9 9z'/></svg>`;

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();

配置项说明

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

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

类型常量

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"

配置 Details

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

const customDetailsIcon = `<svg>...</svg>`;

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

添加新类型的 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" 属性切换：

<div data-theme="dark">
  <!-- 编辑器内容 -->
</div>

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%);
}

架构说明

Details 独立 Schema

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

• HTML <details> 元素要求 <summary> 作为第一个子元素
• 普通容器使用 <div> 结构
• 如果共用 Schema，会导致 DOM 结构不符合 HTML 规范，浏览器原生折叠功能失效

普通容器结构：
<div class="milkdown-container info">
  <div class="milkdown-container-title">标题</div>
  <div class="milkdown-container-content">内容</div>
</div>

Details 结构：
<details class="milkdown-details">
  <summary class="milkdown-details-summary">标题</summary>
  <div class="milkdown-details-content">内容</div>
</details>

斜杠菜单集成

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

注册整个分组

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)
})

注册单个菜单项

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)
})

自定义分组配置

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

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

API 参考

导出内容

// 插件
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 };

命令使用

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

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

许可证

MIT