md-editor-rt

md-editor-rt is a React-based Markdown editor built with JSX and TypeScript. Key features include:

• Toolbar & UI: Shortcut insertion tools, full-screen modes (browser and page-level), and customizable toolbar order/display.
• Themes: Built-in light and dark themes, plus 6 preview themes (default, vuepress, github, cyanosis, mk-cute, smart-blue).
• Content Support: Supports mermaid diagrams (>=1.3.0), katex math formulas (>=1.4.0), and emoji/custom tag extensions.
• Functionality: Keyboard shortcuts, Prettier formatting (via CDN), image pasting/cropping, and multi-language support.
• Modes: Full Editor mode and Preview-only mode.
• Optimization: Supports tree-shaking/on-demand imports (>=4.0.0).

The md-editor-rt package provides several built-in features:

• UI/UX: Toolbar, full-screen mode, and customizable toolbar.
• Themes: Built-in default and dark themes; preview themes include default, vuepress, github, cyanosis, mk-cute, and smart-blue.
• Editing: Shortcut keys, emoji extensions, and prettier beautification (for markdown content only).
• Media: Support for uploading, pasting, or clipping pictures.
• Advanced Rendering: Support for mermaid (>=1.3.0) and katex mathematical formulas (>=1.4.0).
• Localization: Built-in Chinese and English (default is Chinese).
• Performance: On-demand import support (>=4.0.0).

To customize the editor interface, use the toolbar and footer components. Note that registration is not automatic by name; it uses a mapping system.

Mapping Rule: You must use a "numeric placeholder + defToolbars / defFooters" mapping pattern rather than registering by name.

The library separates the editing experience from the rendering result. To customize the editor, you must choose the correct extension path:

1. Editing Experience (CodeMirror 6)

Use codeMirrorExtensions if you want to modify the editor's behavior or appearance. This includes:

• Auto-completion
• Keyboard shortcuts
• Editor themes
• Floating toolbars

2. Rendering Result (markdown-it)

Use markdownItConfig or markdownItPlugins if you want to modify how Markdown is parsed and displayed. This includes:

• Adding new Markdown syntax
• Modifying HTML output for code blocks
• XSS processing
• Adjusting heading IDs

The library's public API is organized into three main layers:

1. Main Components: The primary entry points for users.

   • MdEditor: The full editor component.
   • MdPreview: A standalone read-only rendering component.
   • MdCatalog: The component for displaying the document outline/table of contents.

2. Reusable UI Components: Modular pieces for toolbars and modals.

   • Toolbars: NormalToolbar, DropdownToolbar, ModalToolbar, NormalFooterToolbar.
   • Modals: MdModal.

3. Global Capabilities: Utilities and configuration tools.

   • config: For dependency injection and configuration.
   • XSSPlugin: For security/XSS handling.
   • clearSideEffects: For cleanup.
   • Locales: zh_CN, en_US.

The md-editor-v3 editor supports a wide range of Markdown extensions and syntax, including:

• Basic Formatting: Bold, underline, italics, strikethrough, superscript, subscript, and inline code.
• Lists & Tasks: Ordered lists, unordered lists, and task lists (checkboxes).
• Block Elements: Blockquotes and hyperlinks.
• Media: Images with titles.
• Tables: Standard Markdown table syntax.
• Mathematics: LaTeX math formulas (e.g., using $$ delimiters).
• Diagrams: Mermaid flowchart syntax.
• Admonitions/Callouts: Supports various types including note, abstract, info, tip, success, question, warning, failure, danger, bug, example, quote, hint, caution, error, and attention.

The id and editorId props are critical for linking components together via an internal event bus.

• id: The preferred identifier for new code in MdEditor and MdPreview.
• editorId: Used for backward compatibility and specifically required by MdCatalog to listen to directory changes and handle scroll synchronization.

Warning: When implementing cross-component logic (e.g., linking an editor to a catalog), ensure you are using the correct identifier expected by the target component to avoid broken event channels.

The editor supports a wide range of Markdown extensions and features, including:

• Standard Syntax: Bold, underline, italics, strikethrough, inline code, and hyperlinks.
• Lists: Ordered lists, unordered lists, and task lists (checkboxes).
• Formatting: Superscript (^text^) and subscript (~text~).
• Advanced Blocks:
  • Tables: Standard Markdown table syntax.
  • Mathematical Formulas: LaTeX-style equations using $$ delimiters.
  • Diagrams: Mermaid flowchart syntax.
  • Charts: ECharts configuration blocks using ```echarts.
  • Blockquotes: Standard > syntax.
  • Callouts/Admonitions: Various alert types (e.g., note, tip, warning, danger).

Before implementing, identify which component matches your requirement:

• Editable Markdown: Use MdEditor.
• Read-only Rendering: Use MdPreview.
• Navigation/Table of Contents: Use MdCatalog.
• Custom Toolbars/Footers: Use DropdownToolbar, ModalToolbar, or NormalFooterToolbar.
• Global Dependency/Rendering/Editing Chain Modification: Use config().
• HTML Security: Use sanitize or XSSPlugin.
• Cleaning Default Side Effects: Use clearSideEffects().

By default, md-editor-rt does not include a built-in XSS plugin. You must implement a sanitization strategy.

Strategies:

1. Manual Sanitization: Pass a sanitize(html) function to the sanitize prop of MdPreview.
2. Global Plugin: Use config({ markdownItPlugins }) to integrate the XSSPlugin into the markdown-it pipeline.
3. Specific Sanitization: Use sanitizeMermaid if you need to specifically clean Mermaid diagrams.

Always evaluate your Content Security Policy (CSP) and whether you want to allow native HTML within Markdown.

When injecting local instances for certain features, remember that providing the JavaScript instance is often insufficient. You must also manually include the corresponding CSS for the feature to render correctly.

Key features requiring manual CSS synchronization include:

• highlight.js (Code Highlighting)
• katex (Mathematical Formulas)
• cropperjs (Image Cropping)