Md-preview-CLI

Markdown real-time preview + export

Markdown 实时预览 + 导出工具

CLI + Web + Markdown 三位一体

由于 CLI 对系统兼容性要求高，服务端选择 CommonJS 模块化方式，浏览器采用 ESM

Getting Started

#for repeated use
npm i md-preview-cli-plus
npx md-preview --help #help
npx md-preview README.md --port 5533 --theme dark --export ./666.html #example

#run it once
npx md-preview-cli-plus --help
npx md-preview-cli-plus <file_path> [options]

Features

CLI Construction Built using commander for argument parsing, help information (--help), version control (-V, --version), and robust error handling.

File Watching Utilizes chokidar for efficient, cross-platform file watching with low resource consumption.

File Opening Uses open to launch files or applications across platforms with high compatibility.

Colorful Terminal Output Powered by chalk for vibrant CLI messages 🌈, and highlight.js for syntax highlighting in code blocks.

Hot Module Replacement (HMR) Similar to Vite's HMR: wraps socket.io for both client and server.

• The browser uses useSocket() to listen for server messages.
• Performance optimization for large files: The page partially updates upon receiving a notification.+ debounce
• The server watches file changes and pushes updates to the browser.

HTML Export Feature Supports --export flag to save rendered content as an HTML file.

Theme Support Enables theme switching via --theme=dark and supports custom themes placed in the styles/ folder. Reference implementation available in default.css.

Plugin System Highly flexible plugin architecture with lifecycle hooks.

• Supports custom plugins
• Configuration via .previewrc file and CLI arguments

//.previewrc
{
  "theme": "default",
  "pluginsFolder": [//loading all plugins under these folders
    "./plugins"
  ]
}

• CLI arguments take precedence over config file
• Fault Tolerance If a plugin throws an error, it will be ignored to prevent breaking the core functionality.

Packaging & Distribution Published as an npm package.

🔌 Plugin System

1. Multiple Integration Options:
   • Pass plugin path via CLI arguments.
   • Place plugins inside a directory (e.g. plugins/) and use a configuration file .previewrc.
   • In case of conflicts, CLI arguments have higher priority than .previewrc.
2. Custom Plugin Lifecycle Hooks Supported:
   • init
   • beforeRender
   • afterRender

功能细化

1. 构建CLI 采用commander 解析参数、增加帮助信息--help、版本控制-V --version、错误处理
2. 文件监听变化 chokidar 跨平台兼容性好 低耗能
3. 打开open 打开各种文件程序 跨平台兼容性好
4. 打造彩色终端 🌈chalk，引入代码高亮 highlight.js
5. 热刷新HMR：（类似 Vite）封装socket.io客户端和服务端，浏览器使用useSocket()监听服务端消息，有通知则局部更新页面 ~~（借助morphdom做DOM diff算法）~~ ，服务端监听文件变化并通知浏览器页面更新

性能优化： (1)拆分为逻辑块，手写逻辑块 diff算法对比（按照key比较），将修改块发送给客户端，客户端通过增删逻辑对比替换 (2)更新逻辑的防抖处理：50ms等待时间

6. 导出 HTML 功能：增加 --export 参数保存 HTML 文件
7. 多主题支持：通过 --theme=dark 选择不同样式、支持自定义主题（放在styles文件夹下，代码参考default.css）
8. 插件机制：支持自定义插件及其生命周期钩子、高灵活度配置，支持插件配置文件.previewrc（一键配置加载文件夹下所有插件）+CLI参数优先级控制；容错机制：如果某插件有错误，无视该插件；
9. 打包发布：已发布为 NPM 包
10. 后续：微前端结合文档管理器（传入文件夹）、图床、富文本编辑、插件沙箱机制、vitest单元测试

插件机制

1. 任选其一：可通过命令行传插件地址;也可以将插件放入某个目录下（例如plugins/）并设置插件配置文件.previewrc;如有冲突，则.previewrc配置优先级小于命令行参数
2. 支持自定义插件，插件系统生命周期钩子 init、beforeRender/afterRender

项目结构

md-preview/
├── bin/
│   └── cli.js              # CLI 命令入口
├── lib/
│   ├── pluginManager.js           # 插件加载器
│   ├── preview.js          # 启动本地服务
│   └── renderMarkdown.js   # Markdown 渲染函数
│   └── utils.js   # 多个工具函数，读取配置文件 .previewrc、读取某文件夹下所有插件
├── public/
│   └── hmrServer.js #hmr socket服务器
│   └── useSocket.js #hmr socket客户端
├── styles/
│   └── default.css           # 默认主题样式
│   └── dark.css           # 暗黑主题样式
├── README.md
├── package.json
├── plugins/
│   ├── copyright-plugin.js      # 示例插件 影响最底部文字 可直接删除