# 功能与安装

按需求选择内置包、可选语法、编辑命令与应用负责的能力。

## 基础组合

`@quirekit/msfe-core` 提供编辑实例和扩展协议；`@quirekit/msfe-starter-kit` 组合常用 Markdown 呈现；Vue / React 适配器保留原应用的 Provider 树。安装版本应成组固定，当前公共 API 仍为实验版本。

~~~ts
import { StarterKit } from '@quirekit/msfe-starter-kit'
import { CustomContainer, Footnotes, Math, Mermaid } from '@quirekit/msfe-markdown-extras'
const extensions = [StarterKit, CustomContainer, Footnotes, Math, Mermaid]
~~~

这里展示安装关系；界面、主题、语言高亮及组件控件按对应教程配置。不要把所有包都装入 bundle 才开始使用。

## StarterKit 包含什么

| 功能 | 源码形式 | 编辑入口 |
| --- | --- | --- |
| 标题 | ATX / Setext | `setHeading(level)` |
| 粗体、强调、删除线 | `**bold**`、`*em*`、`~~del~~` | `toggleBold()`、`toggleEmphasis()`、`toggleStrikethrough()` |
| 行内代码和代码块 | code span / fenced / indented | 语言命令及原生源码编辑 |
| 链接与图片 | inline / 可解析引用 | 插入命令与已支持字段的精确写回 |
| 列表和任务项 | 有序、无序、`- [ ]` | `indentList()`、`outdentList()`、`continueList()`、任务控件 |
| 引用、分隔线 | `>`、主题分隔线 | 原生源码编辑和呈现 |
| GFM 表格 | pipe table | 行列命令与原生单元格文本 |
| 字面值 | 转义、实体、换行 | 源码中立的显示处理 |

不同语法形式不一定拥有同样的可写字段。可以读取或渲染，不等于能用任意 `updateAttributes()` 改写。修改前用 `can()`、语义查询及对应 codec 的支持范围判断。

## 表格与列表命令

~~~ts
editor.commands.insertTableRow('after')
editor.commands.insertTableColumn('before')
editor.commands.moveTableCell(1)
editor.commands.deleteTableRow()
editor.commands.indentList()
~~~

这些命令由 `@quirekit/msfe-prose` 的相关功能安装。需要当前选区位于可操作结构，删除最后一行/列等情况有适用性限制。表格仍是 GFM 源码，不支持把任意富文本块塞进一个单元格。命令链和失败处理见 [命令](/guide/commands)。

## 可选 Markdown 扩展

以下导出来自 `@quirekit/msfe-markdown-extras`，默认不全包含在 StarterKit 中。

| 扩展 | 用法示意 | 需要注意 |
| --- | --- | --- |
| `Frontmatter` | 文件开头 YAML 围栏 | 源码呈现，不提供业务配置对象编辑器 |
| `DocumentProperties` | 可选 YAML 属性表，依赖 `Frontmatter` | 显式安装；源码模式保留原文，可同实例关闭 |
| `Subscript` / `Superscript` | `H~2~O` / `x^2^` | 与删除线区分，未确认语法回退 |
| `InsertedText` / `Highlight` | `++added++` / `==marked==` | 显示样式需接入主题 |
| `Emoji` | `:smile:` / 可选表情符号 | Unicode 呈现，可配置 definitions / emoticons |
| `DefinitionList` | 术语下一行 `: definition` | 正文仍由 Markdown 解析 |
| `Abbreviations` | `*[HTML]: Hyper Text Markup Language` | 缩写索引与源文本分离 |
| `Footnotes` | `[^key]`、定义及内联脚注 | 编号按源码引用关系；支持查询/导航 |
| `Typographer` | 引号、破折号等视觉替换 | 不改变保存源码；可配置引号和有界扫描 |
| `Callout` | 引用中的 `[!NOTE]` 等 | 主题角色样式；区别于冒号容器 |
| `CustomContainer` | `::: warning` | 注册类型、嵌套和折叠见 [容器](/extensions/containers) |
| `Math` | `$...$` 与 `$$...$$` | KaTeX 预览、源码回退，无结构化公式命令 |
| `Mermaid` | `mermaid` 围栏 | 可选异步预览，见 [图表](/extensions/diagrams) |

~~~ts
import { Emoji, Typographer, Footnotes } from '@quirekit/msfe-markdown-extras'
const emoji = Emoji.configure({ definitions: { ship: '🚢' }, emoticons: false })
const typography = Typographer.configure({ smartQuotes: true, quotes: ['“', '”', '‘', '’'] })
const footnotes = Footnotes.configure({
  referenceLabel: number => `脚注 ${number}`,
  definitionLabel: number => `返回脚注 ${number}`,
})
~~~

数学样式需要宿主加载 KaTeX CSS（例如 `katex/dist/katex.min.css`），并在 SSR 应用的全局样式入口引入。`Math`、`Mermaid` 可通过 `controls` 使用自己的预览操作组件。

脚注高级读取使用 `queryFootnotes()`，导航用 `navigateFootnote()`，缩写使用 `queryAbbreviations()`。查询存在 pending 状态；不要自行扫描全文取代已有索引，也不要假设显示编号是永久 ID。

## HTML 是单独的能力

`@quirekit/msfe-html` 导出 `Html`，默认保留源码；`Html.configure({ rendering: 'safe' })` 才启用受限的安全呈现。图片加载还需要 `allowImage` 明确允许。脚本、任意 HTML 编辑、任意嵌入和浏览器完整 HTML 布局不属于承诺。

HTML 视觉偏好可通过该包的公开函数调整；不应因阅读模式切换而重写 Markdown。遇到不支持结构时保持源码比不可逆地丢掉标签更可靠。

## 应用需要自行提供

保存服务、文件打开、上传、路由、权限、外部导航、HTML/PDF 导出和 Yjs 协同协议都由宿主接入。`applyChanges` 提供版本校验，不是完整的协同适配器。第三方 markdown-it / ProseMirror / Tiptap 插件不能直接安装；迁移入口见 [Markdown 插件](/extensions/markdown-plugins)。

选择下一步：[节点](/extensions/custom-node)、[容器](/extensions/containers)、[图表](/extensions/diagrams)、[主题](/customization/theme)、[保存](/guide/saving)。