ByteMD Documentation

ByteMD supports standard Markdown syntax and various extended features through plugins. Supported syntax includes:

• Basic Syntax: Bold (**text**), Italics (_text_), Links ([text](url)), Ordered/Unordered Lists, and Blockquotes.
• GFM (GitHub Flavored Markdown): Automatic URL linking, Strikethrough (~~text~~), Task lists (- [x]), and Tables.
• Footnotes: Using [^1] syntax for references and [^1]: content for definitions.
• Gemoji: Emoji shortcodes like :+1: or :family_man_man_boy_boy:.
• Math Equations: Inline math using $a+b$ and block math using $$ delimiters.
• Mermaid Diagrams: Rendering diagrams using mermaid code blocks.

ByteMD leverages the remark and rehype ecosystems to process Markdown through a multi-step pipeline. Customization is primarily achieved through three specific steps in this lifecycle:

1. Markdown Parsing: Text is parsed into a Markdown AST (mdast).
2. Remark Manipulation (Step 2): The Markdown AST is modified using remark plugins. (Customizable)
3. HTML Transformation: The Markdown AST is converted to an HTML AST.
4. Sanitization: The HTML AST is sanitized for security.
5. Rehype Manipulation (Step 5): The HTML AST is modified using rehype plugins. (Customizable)
6. Stringification: The HTML AST is converted to an HTML string.
7. DOM Manipulation (Step 7): Extra DOM manipulation occurs after rendering. (Customizable)

Developers can hook into steps 2, 5, and 7 to implement custom logic.

ByteMD consists of two primary components:

1. Editor: A full Markdown editor component that allows users to write and edit Markdown content. It includes a preview mode.
2. Viewer: A component used to display rendered Markdown results without editing capabilities.

Important: Before using either component, you must import the ByteMD CSS file to ensure correct styling:

import 'bytemd/dist/index.css'

The @bytemd/plugin-math-ssr plugin enables math formula support in ByteMD while remaining compatible with Server-Side Rendering (SSR). To use it, you must import the plugin, include it in the plugins array of your Editor configuration, and ensure that the KaTeX CSS is imported into your project to render the formulas correctly.

Note: You must import katex/dist/katex.css for the math formulas to display with proper styling.

import math from '@bytemd/plugin-math-ssr'
import { Editor } from 'bytemd'
import 'katex/dist/katex.css'

new Editor({
  target: document.body,
  props: {
    plugins: [
      math(),
      // ... other plugins
    ],
  },
})

The @bytemd/plugin-math plugin enables math formula support within the ByteMD editor. To use it, you must import the math plugin, register it in the plugins array of the Editor configuration, and importantly, import the KaTeX CSS to ensure formulas are rendered correctly.

Requirements:

• bytemd
• @bytemd/plugin-math
• katex (for the CSS)

import math from '@bytemd/plugin-math'
import { Editor } from 'bytemd'
import 'katex/dist/katex.css'

new Editor({
  target: document.body,
  props: {
    plugins: [
      math(),
      // ... other plugins
    ],
  },
})

After creating the project and installing dependencies (npm install, pnpm install, or yarn), use the following commands to manage your development lifecycle:

Start development server:

npm run dev

Start development server and open in browser:

npm run dev -- --open

Build for production:

npm run build

Preview production build:

npm run preview

Note: To deploy, you may need to install a SvelteKit adapter for your specific target environment.

The default height of the ByteMD Editor is 300px. You can override this using CSS. To change the height of the container, target the .bytemd class:

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

Other styles can be found in the default style source.

To add Mermaid diagram support to your ByteMD editor, install the @bytemd/plugin-mermaid package and include it in the plugins array of your Editor configuration. The plugin is initialized by calling mermaid() as a function within the plugins list.

import mermaid from '@bytemd/plugin-mermaid'
import { Editor } from 'bytemd'

new Editor({
  target: document.body,
  props: {
    plugins: [
      mermaid(),
      // ... other plugins
    ],
  },
})