ByteMD

这是 ByteMD v1 仓库。

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

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

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

特性

1. 轻量级且框架无关：ByteMD 使用 Svelte 构建。它编译为原生 JS DOM 操作，无需导入任何 UI 框架运行时包，这使得它轻量级，并且易于适配其他库/框架。
2. 易于扩展：ByteMD 具有插件系统，可以扩展基本的 Markdown 语法，从而轻松添加代码语法高亮、数学公式和 Mermaid 流程图等附加功能。如果这些插件不能满足你的需求，你还可以编写自己的插件。
3. 默认安全：ByteMD 已正确处理了 跨站脚本攻击(XSS)，如 <script> 和 <img onerror>。无需引入额外的 DOM 清理步骤。
4. 兼容 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

Editor

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

样式自定义

编辑器

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。完整的处理过程如下：

1. Markdown 文本被解析成 AST
2. Markdown AST 可以通过多个 remark 插件 进行操作
3. Markdown AST 被转换为 HTML AST
4. 出于安全考虑，HTML AST 会被净化
5. HTML AST 可以通过多个 rehype 插件 进行操作
6. HTML AST 被序列化为 HTML
7. 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()
          },
        },
      },
    ],
  }
}

现在我们完成了插件的最小版本！更多细节和参考请查看源代码。

贡献者

许可证

MIT