Awesome Open Source
Awesome Open Source

ByteMD

test

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

Features

  1. 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.
  2. 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.
  3. 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.
  4. 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 npm gzip size Svelte/Vanilla JS component
@bytemd/react npm gzip size React component
@bytemd/vue npm gzip size Vue component

Legacy browsers support

The default entry of NPM package only supports modern browsers. There are two ways to make legacy browsers (IE9+) work:

  1. Compile it with ESNext -> ES5 transpilers, such as Babel
  2. Use the ES5 bundle(dist/index.es5.js)

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.min.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 { Editor, Viewer } from '@bytemd/react'
import gfm from '@bytemd/plugin-gfm'

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 { Editor, Viewer } from '@bytemd/vue'
import gfm from '@bytemd/plugin-gfm'

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 { Editor, Viewer } from 'bytemd'
import gfm from '@bytemd/plugin-gfm'

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

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
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/lib/locales
uploadImages function Specify how to upload images
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.

Technical details

ByteMD uses remark and rehype ecosystem to process Markdown. The complete process is as follows:

  1. The markdown text is parsed to an AST
  2. The Markdown AST could be manipulated by several remark plugins
  3. The Markdown AST is transformed to a HTML AST
  4. The HTML AST is sanitized for security reason
  5. The HTML AST could be manipulated by several rehype plugins
  6. The HTML AST is stringified to HTML
  7. Some extra DOM manipulation after the HTML being rendered

It could also be described as a flowchart:

process

The 2,5,7 steps are designed for user customization via ByteMD plugin API.

Plugins

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

Write a plugin

TODO: plugin API not stable yet

Contributors

License

MIT


Get A Weekly Email With Trending Projects For These Topics
No Spam. Unsubscribe easily at any time.
Typescript (252,254
Markdown (6,597
Svelte (3,611
Markdown Editor (408
Related Projects