ByteMD

这是 ByteMD v1 仓库。

v2 正在积极开发中，请查看 HashMD。

ByteMD 是一个使用 Svelte 构建的 Markdown 编辑器组件。它也可以在 React、Vue 和 Angular 等其他库/框架中使用。

在线演示：https://bytemd.js.org/playground/

特性

轻量级且框架无关：ByteMD 使用 Svelte 构建。它编译为原生 JS DOM 操作，无需导入任何 UI 框架运行时包，这使得它轻量级，并且易于适配其他库/框架。
易于扩展：ByteMD 具有插件系统，可以扩展基本的 Markdown 语法，从而轻松添加代码语法高亮、数学公式和 Mermaid 流程图等附加功能。如果这些插件不能满足你的需求，你还可以编写自己的插件。
默认安全：ByteMD 已正确处理了跨站脚本攻击(XSS)，如 <script> 和 <img onerror>。无需引入额外的 DOM 清理步骤。
兼容 SSR：ByteMD 可以在服务器端渲染(SSR) 环境中使用，无需额外配置。在某些情况下，由于 SSR 具有更好的 SEO 和在慢速网络连接下更快的内容呈现时间，因此被广泛使用。

安装

包名	状态	描述
bytemd		Svelte/原生 JS 组件
@bytemd/react		React 组件
@bytemd/vue		Vue 2 组件
@bytemd/vue-next		Vue 3 组件

旧版浏览器支持

NPM 包的默认入口仅支持现代浏览器。要使旧版浏览器（IE9+）正常工作，你可以使用 ESNext -> ES5 转译器进行编译，如 Babel 或 SWC。

1.11.0 版本之后将不再提供 ES5 打包文件。如果你需要，可以使用 1.11.0 版本或更早版本

请注意，未包含 polyfills，需要手动导入，请参阅旧版浏览器示例。

使用

有两个组件：Editor 和 Viewer。Editor 是 Markdown 编辑器，顾名思义；Viewer 通常用于显示渲染后的 Markdown 结果，不可编辑。

在使用组件之前，记得导入 CSS 文件以确保样式正确：

import 'bytemd/dist/index.css'

Svelte

<script>
  import { Editor, Viewer } from 'bytemd'
  import gfm from '@bytemd/plugin-gfm'

  let value
  const plugins = [
    gfm(),
    // 在此添加更多插件
  ]

  function handleChange(e) {
    value = e.detail.value
  }
</script>

<template>
  <Editor {value} {plugins} on:change={handleChange} />
</template>

React

import gfm from '@bytemd/plugin-gfm'
import { Editor, Viewer } from '@bytemd/react'

const plugins = [
  gfm(),
  // 在此添加更多插件
]

const App = () => {
  const [value, setValue] = useState('')

  return (
    <Editor
      value={value}
      plugins={plugins}
      onChange={(v) => {
        setValue(v)
      }}
    />
  )
}

Vue

<template>
  <Editor :value="value" :plugins="plugins" @change="handleChange" />
</template>

<script>
import gfm from '@bytemd/plugin-gfm'
import { Editor, Viewer } from '@bytemd/vue'

const plugins = [
  gfm(),
  // 在此添加更多插件
]

export default {
  components: { Editor },
  data() {
    return { value: '', plugins }
  },
  methods: {
    handleChange(v) {
      this.value = v
    },
  },
}
</script>

原生 JS

import gfm from '@bytemd/plugin-gfm'
import { Editor, Viewer } from 'bytemd'

const plugins = [
  gfm(),
  // 在此添加更多插件
]

const editor = new Editor({
  target: document.body, // 要渲染的 DOM
  props: {
    value: '',
    plugins,
  },
})

editor.$on('change', (e) => {
  editor.$set({ value: e.detail.value })
})

选项

Viewer

键	类型	描述
`value`	`string` (必填)	Markdown 文本
`plugins`	`BytemdPlugin[]`	ByteMD 插件列表
`sanitize`	`(schema: Schema) => Schema`	清理策略
`remarkRehype`	文档	remark-rehype 配置选项

Editor

Editor 组件也接受 Viewer 的预览选项。此外，还有一些其他选项：

键	类型	描述
`mode`	`split`, `tab`, `auto`	编辑器显示模式，默认：`auto`
`previewDebounce`	`number`	预览的防抖时间（毫秒），默认：`300`
`placeholder`	`string`	编辑器占位符
`editorConfig`	文档	CodeMirror 编辑器配置
`locale`		i18n 语言设置。可用语言可在 `bytemd/locales` 中找到，默认：使用 `en.json`
`uploadImages`	`function`	指定如何上传图片。如果设置，工具栏上将显示图片图标
`maxLength`	`number`	值的最大长度（字符数）

样式自定义

编辑器

ByteMD 编辑器的默认高度为 300px。可以通过 CSS 覆盖：

.bytemd {
  height: calc(100vh - 200px);
}

其他样式也可以被覆盖，请参见默认样式。

查看器

查看器没有内置样式。你可以使用第三方 Markdown 主题，例如 juejin-markdown-themes 和 github-markdown-css。

插件系统

ByteMD 提供了强大的插件系统用于自定义。有几个官方插件支持代码语法高亮、数学公式和 Mermaid 流程图等功能。

如果你有更多自定义需求，也可以编写自己的插件来支持它们。

官方插件

包	状态	描述
@bytemd/plugin-breaks		支持换行
@bytemd/plugin-frontmatter		解析前置元数据
@bytemd/plugin-gemoji		支持 Gemoji 短代码
@bytemd/plugin-gfm		支持 GFM（自动链接、删除线、表格、任务列表）
@bytemd/plugin-highlight		代码块高亮
@bytemd/plugin-highlight-ssr		代码块高亮（兼容 SSR）
@bytemd/plugin-math		支持数学公式
@bytemd/plugin-math-ssr		支持数学公式（兼容 SSR）
@bytemd/plugin-medium-zoom		像 Medium 一样缩放图片
@bytemd/plugin-mermaid		支持 Mermaid 图表

技术概述

ByteMD 使用 remark 和 rehype 生态系统来处理 Markdown。完整的处理过程如下：

Markdown 文本被解析成 AST
Markdown AST 可以通过多个 remark 插件进行操作
Markdown AST 被转换为 HTML AST
出于安全考虑，HTML AST 会被净化
HTML AST 可以通过多个 rehype 插件进行操作
HTML AST 被序列化为 HTML
HTML 渲染后进行一些额外的 DOM 操作

这个过程也可以用流程图描述：

插件系统

第 2、5、7 步骤是为用户通过 ByteMD 插件 API 进行自定义设计的。

编写插件

我们以数学公式插件为例，带你了解整个过程。

首先，根据 BytemdPlugin 类型签名搭建项目框架：

import type { BytemdPlugin } from 'bytemd'

export default function mathPlugin(): BytemdPlugin {
  return {
    // 待实现
  }
}

然后我们仔细看看需求：如果我们想要将 $a+b$ 这样的语法渲染成数学公式，需要做以下几件事：

在 Markdown 中支持 $a+b$ 语法作为数学公式（第 2 步）
在 HTML 中正确渲染这些节点（第 5 步或第 7 步）
另外，在工具栏中添加一个额外的图标会给用户带来便利

对于第一件事，幸运的是，我们不需要自己实现，因为 remark-math 已经做到了。我们只需要导入并使用它：

import type { BytemdPlugin } from 'bytemd'
+import remarkMath from 'remark-math'

export default function mathPlugin(): BytemdPlugin {
  return {
-    // 待实现
+    remark: (processor) => processor.use(remarkMath),
  }
}

然后考虑第二件事，这会稍微复杂一些，因为我们有两个选择：在第 5 步或第 7 步进行。区别在于第 5 步更适合 SSR，而第 7 步将渲染交给客户端。这就是为什么我们有两个插件：@bytemd/plugin-math 和 @bytemd/plugin-math-ssr。

// 如果我们选择第 5 步：
import type { BytemdPlugin } from 'bytemd'
import remarkMath from 'remark-math'
+import rehypeKatex from 'rehype-katex'

export default function mathPlugin(): BytemdPlugin {
  return {
    remark: (processor) => processor.use(remarkMath),
+   rehype: (processor) => processor.use(rehypeKatex),
  }
}

// 如果我们选择第 7 步：
import type { BytemdPlugin } from 'bytemd'
import remarkMath from 'remark-math'
+import rehypeKatex from 'rehype-katex'

export default function mathPlugin(): BytemdPlugin {
  return {
    remark: (processor) => processor.use(remarkMath),
+   viewerEffect({ markdownBody }) {
+     const renderMath = async (selector: string, displayMode: boolean) => {
+       const katex = await import('katex').then((m) => m.default)
+
+       const els = markdownBody.querySelectorAll<HTMLElement>(selector)
+       els.forEach((el) => {
+         katex.render(el.innerText, el, { displayMode })
+       })
+     }
+
+     renderMath('.math.math-inline', false)
+     renderMath('.math.math-display', true)
+   },
  }
}

最后一件事是在工具栏中添加一个图标。我们使用 actions 属性来实现：

export default function mathPlugin(): BytemdPlugin {
  return {
    actions: [
      {
        title: '插入数学公式',
        icon: '', // 16x16 SVG 图标
        handler: {
          type: 'action',
          click(ctx) {
            // 待实现：
            // `ctx` 是 `BytemdEditorContext` 的一个实例，它有
            // 几个实用方法来帮助操作 CodeMirror 编辑器状态。

            // 记得调用 `focus` 以避免失去焦点
            editor.focus()
          },
        },
      },
    ],
  }
}