ByteMD

This is ByteMD v1 repository.

v2 is under development actively, see HashMD.

ByteMD is a Markdown editor component built with Svelte. It could also be used in other libraries/frameworks such as React, Vue and Angular.

Playground here: https://bytemd.js.org/playground/

Features

Lightweight and framework agnostic: ByteMD is built with Svelte. It compiles to vanilla JS DOM manipulation without importing any UI Framework runtime bundle, which makes it lightweight, and easily adapted to other libraries/frameworks.
Easy to extend: ByteMD has a plugin system to extend the basic Markdown syntax, which makes it easy to add additional features such as code syntax highlight, math equation and Mermaid flowcharts. You can also write your own plugin if these ones don't meet your needs.
Secure by default: Cross-site scripting(XSS) attack such as <script> and <img onerror> have been correctly handled by ByteMD. No need to introduce extra DOM sanitize steps.
SSR compatible: ByteMD could be used in the Server-side rendering(SSR) environment without extra config. SSR is widely used in some cases due to its better SEO and fast time-to-content in slow network connection.

Installation

| Package | Status | Description | | --- | --- | --- | | bytemd | | Svelte/Vanilla JS component | | @bytemd/react | | React component | | @bytemd/vue | | Vue 2 component | | @bytemd/vue-next | | Vue 3 component |

Legacy browsers support

The default entry of NPM package only supports modern browsers. To make legacy browsers (IE9+) work, You can compile it with ESNext -> ES5 transpilers, such as Babel or SWC.

The ES5 bundle will no longer be available after version 1.11.0. If you need it, you can use version 1.11.0 or earlier versions

Notice that polyfills are not included, and should be imported manually, see the legacy browser example.

Usage

There are two components: Editor and Viewer. Editor is the Markdown editor, as the name suggests; Viewer is commonly used to display rendered Markdown results without editing.

Before using the component, remember to import CSS file to make styles correct:

import 'bytemd/dist/index.css'

Svelte

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

  let value
  const plugins = [
    gfm(),
    // Add more plugins here
  ]

  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(),
  // Add more plugins here
]

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(),
  // Add more plugins here
]

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

Vanilla JS

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

const plugins = [
  gfm(),
  // Add more plugins here
]

const editor = new Editor({
  target: document.body, // DOM to render
  props: {
    value: '',
    plugins,
  },
})

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

Options

Viewer

| Key | Type | Description | | --- | --- | --- | | value | string (required) | Markdown text | | plugins | BytemdPlugin[] | ByteMD plugin list | | sanitize | (schema: Schema) => Schema | Sanitize strategy | | remarkRehype | documentation | remark-rehype config options |

Editor

Editor component also accepts the options of Viewer for preview. Besides that, there are some other options:

| Key | Type | Description | | --- | --- | --- | | mode | split, tab, auto | Editor display mode, default: auto | | previewDebounce | number | Debounce time (ms) for preview, default: 300 | | placeholder | string | Editor placeholder | | editorConfig | documentation | CodeMirror editor config | | locale | | i18n locale. Available locales could be found at bytemd/locales, default: use en.json | | uploadImages | function | Specify how to upload images. If set, the image icon will appear on the toolbar | | maxLength | number | Maximum length (number of characters) of value |

Style customization

Editor

The default height of ByteMD Editor is 300px. It could be overridden by CSS:

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

The other styles could also be overridden, see the default style.

Viewer

There is no built-in styles for the Viewer. You could use third-party markdown themes, for example juejin-markdown-themes and github-markdown-css.

Plugin System

ByteMD provides a powerful plugin system for customization. There are several official plugins to support features such as code syntax highlight, math equation and Mermaid flowcharts.

If you have more customized needs, you could also write your own plugin to support them.

Official Plugins

| Package | Status | Description | | --- | --- | --- | | @bytemd/plugin-breaks | | Support breaks | | @bytemd/plugin-frontmatter | | Parse frontmatter | | @bytemd/plugin-gemoji | | Support Gemoji shortcodes | | @bytemd/plugin-gfm | | Support GFM (autolink literals, strikethrough, tables, tasklists) | | @bytemd/plugin-highlight | | Highlight code blocks | | @bytemd/plugin-highlight-ssr | | Highlight code blocks (SSR compatible) | | @bytemd/plugin-math | $npm$ | Support math formula | | @bytemd/plugin-math-ssr | $npm$ | Support math formula (SSR compatible) | | @bytemd/plugin-medium-zoom | | Zoom images like Medium | | @bytemd/plugin-mermaid | | Support Mermaid diagram |