md2ui 1.0.19 → 1.0.20

package/README.md

@@ -4,27 +4,72 @@
 [![GitHub](https://img.shields.io/badge/GitHub-xiaoyaodev%2Fmd2ui-blue?logo=github)](https://github.com/xiaoyaodev/md2ui)
 [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
 
-一个轻量级的 Markdown 文档渲染工具，将本地 `.md` 文件转换为美观的 HTML 页面。支持实时预览和静态站点生成（SSG）两种模式。
+轻量级 Markdown 文档站点工具，一行命令将本地 `.md` 文件转换为可预览、可编辑、可搜索的文档站点。
 
-## 功能特性
+## 为什么需要 md2ui？
 
-- 自动目录树 - 扫描文档文件夹，自动生成多级导航，支持搜索过滤
-- 三栏布局 - 左侧导航 / 中间内容 / 右侧大纲，可拖拽调整宽度
-- Markdown 增强 - GFM 语法、代码高亮、Mermaid 图表、Frontmatter
-- 全文搜索 - 基于 MiniSearch 的快速全文检索
-- 移动端适配 - 响应式布局，抽屉式导航和目录
-- 阅读体验 - 阅读进度条、预计阅读时间、上下篇导航
-- SSG 构建 - `md2ui build` 生成纯静态 HTML，可直接部署
+AI 编程时代，Cursor、Copilot、Kiro 等工具正在改变我们的开发方式。与 AI 协作的过程中，会产生大量的 Markdown 文档 —— 需求文档、设计方案、API 文档、会议纪要、技术调研……
+
+这些 `.md` 文件散落在项目各处，带来了一系列痛点：
+
+- 文件越来越多，找一篇文档要翻半天
+- IDE 的 Markdown 预览体验一般，表格、流程图、数学公式渲染不理想
+- 想快速改几个字，还得切回编辑器找到对应文件
+- 文档之间缺乏导航关系，无法形成知识体系
+- 想分享给团队成员，还得额外搭建文档站
+
+md2ui 就是为了解决这些问题而生的。把它指向你的文档目录，立刻获得一个功能完整的文档站点。
+
+## 核心能力
+
+- 零配置启动 - `cd docs && md2ui`，开箱即用
+- 实时预览 - 文件变更自动刷新，所见即所得
+- 在线编辑 - 内置富文本编辑器，直接在浏览器中修改并保存到本地文件
+- 全文搜索 - 基于 MiniSearch，毫秒级检索所有文档内容
+- 自动导航 - 扫描目录结构自动生成多级目录树，支持拖拽排序
+- 三栏布局 - 左侧导航 / 中间内容 / 右侧大纲，宽度可拖拽调整
+- Markdown 增强 - GFM 语法、代码高亮、Mermaid 图表、数学公式、Frontmatter
+- 移动端适配 - 响应式布局，手机上也能舒适阅读
+- 阅读体验 - 进度条、预计阅读时间、上下篇导航、图片放大
+- SSG 构建 - `md2ui build` 生成纯静态站点，可直接部署
 - 自定义配置 - 站点标题、主题色、GitHub 链接、页脚等
 
-## 安装使用
+## 界面预览
+预览模式
+![预览模式](imgs/1.png)
+编辑模式
+
+![编辑模式](imgs/2.png)
+
+## 典型使用场景
+
+**AI 辅助开发的文档管理**
+
+用 AI 生成的需求文档、设计方案、技术调研统一放到一个目录，md2ui 提供即时预览和编辑，让文档真正流动起来。
+
+**个人知识库**
 
-### 全局安装
+日常笔记、学习记录、读书摘要，用 Markdown 写完丢进文件夹，md2ui 自动组织成可浏览的知识站点。
+
+**项目文档站**
+
+API 文档、部署指南、开发规范，`md2ui build` 一键构建为静态站点，部署到任意服务器。
+
+**团队协作文档**
+
+配合 Git 管理文档版本，本地用 md2ui 预览和编辑，提交后自动构建部署。
+
+## 快速开始
+
+### 安装
 
 ```bash
-pnpm add -g md2ui
-# 或
+# 需要提前安装nodejs运行环境
 npm install -g md2ui
+
+
+# 免安装 一次性运行
+npx  md2ui
 ```
 
 ### 实时预览
@@ -36,21 +81,19 @@ cd /path/to/your/docs
 md2ui
 ```
 
-指定端口：
+访问 http://localhost:3000 即可查看文档。支持 `-p` 参数指定端口：
 
 ```bash
 md2ui -p 8080
 ```
 
-访问 http://localhost:3000 查看文档（默认端口 3000）。
-
 ### 静态构建
 
 ```bash
 md2ui build
 ```
 
-生成的静态文件在 `dist/` 目录下，可直接部署到任意静态服务器。
+生成的静态文件在 `dist/` 目录下，可直接部署到 Nginx、GitHub Pages、Vercel 等任意静态托管服务。
 
 ## 文档组织
 
@@ -65,8 +108,8 @@ your-docs/
 ```
 
 - 使用 `序号-名称.md` 格式控制排序，如 `01-快速开始.md`
-- 文件夹也支持序号前缀，如 `02-进阶指南/`
-- 序号越小越靠前
+- 文件夹同样支持序号前缀，如 `02-进阶指南/`
+- 支持任意层级嵌套
 
 ## 自定义配置
 
@@ -79,7 +122,7 @@ export default {
   port: 8080,
   folderExpanded: true,
   themeColor: '#3eaf7c',
-  github: 'https://github.com/xiaoyaodev/md2ui',
+  github: 'https://github.com/your/repo',
   footer: 'Copyright © 2025'
 }
 ```
@@ -113,6 +156,8 @@ md2ui/
 │   ├── App.vue            # 主组件
 │   ├── components/        # Vue 组件
 │   ├── composables/       # 组合式函数
+│   ├── extensions/        # Tiptap 编辑器扩展
+│   ├── services/          # 文档服务
 │   ├── config.js          # 共享配置
 │   └── style.css          # 全局样式
 ├── public/docs/           # 示例文档

package/bin/build.js

@@ -574,8 +574,19 @@ function getSsgCss(pkgRoot) {
 
 // ===== 主构建流程 =====
 async function build() {
+  // 解析位置参数：md2ui build [dir]
+  const args = process.argv.slice(3)
+  let targetDir = null
+  for (const arg of args) {
+    if (!arg.startsWith('-')) {
+      targetDir = arg
+      break
+    }
+  }
+  const scanDir = targetDir ? resolve(userDir, targetDir) : userDir
+
   console.log('\n  md2ui build - 静态站点生成\n')
-  console.log(`  扫描目录: ${userDir}\n`)
+  console.log(`  扫描目录: ${scanDir}\n`)
 
   // 加载配置
   const userConfig = await loadUserConfig()
@@ -583,7 +594,7 @@ async function build() {
   const outDir = resolve(userDir, siteConfig.outDir || 'dist')
 
   // 扫描文档
-  const docsList = scanDocs(userDir, '', 0, siteConfig.folderExpanded)
+  const docsList = scanDocs(scanDir, '', 0, siteConfig.folderExpanded)
   const flatDocs = flattenDocs(docsList)
 
   if (flatDocs.length === 0) {

package/bin/md2ui.js

@@ -63,11 +63,14 @@ async function loadUserConfig() {
 // 解析命令行参数
 function parseArgs() {
   const args = process.argv.slice(2)
-  const result = {}
+  const result = { dir: null }
   for (let i = 0; i < args.length; i++) {
     if (args[i] === '-p' || args[i] === '--port') {
       result.port = parseInt(args[i + 1]) || undefined
       i++
+    } else if (!args[i].startsWith('-')) {
+      // 位置参数作为扫描目录
+      result.dir = args[i]
     }
   }
   return result
@@ -131,7 +134,7 @@ function hasMdFiles(dir) {
 }
 
 // Vite 插件：提供用户文档 API + 配置 API + 热更新
-function md2uiPlugin(siteConfig) {
+function md2uiPlugin(siteConfig, docsRoot) {
   return {
     name: 'md2ui-server',
     configureServer(server) {
@@ -139,7 +142,7 @@ function md2uiPlugin(siteConfig) {
       server.middlewares.use((req, res, next) => {
         // 文档列表 API（带 ETag 支持，避免轮询时重复传输）
         if (req.url === '/@user-docs-list') {
-          const docs = scanDocs(userDir, '', 0, siteConfig.folderExpanded)
+          const docs = scanDocs(docsRoot, '', 0, siteConfig.folderExpanded)
           const body = JSON.stringify(docs)
           const etag = '"' + crypto.createHash('md5').update(body).digest('hex') + '"'
           if (req.headers['if-none-match'] === etag) {
@@ -172,8 +175,8 @@ function md2uiPlugin(siteConfig) {
                 res.statusCode = 400; res.end('缺少文档路径'); return
               }
 
-              const docDir = dirname(resolve(userDir, docPath))
-              if (!docDir.startsWith(userDir)) {
+              const docDir = dirname(resolve(docsRoot, docPath))
+              if (!docDir.startsWith(docsRoot)) {
                 res.statusCode = 403; res.end('禁止访问'); return
               }
 
@@ -187,7 +190,7 @@ function md2uiPlugin(siteConfig) {
 
               fs.writeFileSync(targetPath, body)
 
-              // 返回相对于用户目录的路径（对路径各段做 URL 编码）
+              // 返回相对于文档根目录的路径（对路径各段做 URL 编码）
               const docDirRel = dirname(docPath)
               const encodedDir = docDirRel && docDirRel !== '.'
                 ? docDirRel.split('/').map(encodeURIComponent).join('/')
@@ -206,7 +209,7 @@ function md2uiPlugin(siteConfig) {
         }
         // 文档内容
         if (req.url?.startsWith('/@user-docs/')) {
-          const filePath = resolve(userDir, decodeURIComponent(req.url.replace('/@user-docs/', '')))
+          const filePath = resolve(docsRoot, decodeURIComponent(req.url.replace('/@user-docs/', '')))
           if (fs.existsSync(filePath)) {
             // 根据扩展名设置 Content-Type
             const extName = filePath.split('.').pop().toLowerCase()
@@ -254,10 +257,14 @@ function md2uiPlugin(siteConfig) {
 }
 
 async function start() {
+  // 解析参数，支持位置参数指定扫描目录
+  const cliArgs = parseArgs()
+  const scanDir = cliArgs.dir ? resolve(userDir, cliArgs.dir) : userDir
+
   console.log(`\n  md2ui - Markdown 文档预览工具\n`)
-  console.log(`  扫描目录: ${userDir}\n`)
+  console.log(`  扫描目录: ${scanDir}\n`)
 
-  if (!hasMdFiles(userDir)) {
+  if (!hasMdFiles(scanDir)) {
     console.log('  当前目录下没有找到 Markdown 文件 (.md)\n')
     console.log('  请在包含 .md 文件的目录中运行此命令\n')
     process.exit(1)
@@ -265,15 +272,21 @@ async function start() {
 
   // 加载配置
   const userConfig = await loadUserConfig()
-  const cliArgs = parseArgs()
   const siteConfig = { ...defaultConfig, ...userConfig, ...cliArgs }
+  delete siteConfig.dir
 
   const server = await createServer({
     root: pkgRoot,
-    configFile: resolve(pkgRoot, 'vite.config.js'),
-    plugins: [md2uiPlugin(siteConfig)],
+    configFile: false,
+    plugins: [
+      (await import('@vitejs/plugin-vue')).default(),
+      md2uiPlugin(siteConfig, scanDir)
+    ],
     server: {
       port: siteConfig.port
+    },
+    optimizeDeps: {
+      include: ['vue', 'marked', 'mermaid']
     }
   })
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "md2ui",
-  "version": "1.0.19",
+  "version": "1.0.20",
   "type": "module",
   "description": "将本地 Markdown 文档转换为美观的 HTML 页面",
   "author": "",
@@ -54,7 +54,7 @@
     "katex": "^0.16.45",
     "lucide-vue-next": "^0.556.0",
     "marked": "^11.1.1",
-    "mermaid": "^10.6.1",
+    "mermaid": "^11.14.0",
     "minisearch": "^7.2.0",
     "tiptap-markdown": "^0.9.0",
     "vite": "^5.0.0",

package/public/docs/02-Markdown/346/270/262/346/237/223/00-/345/237/272/347/241/200/350/257/255/346/263/225.md

@@ -36,6 +36,8 @@
 > console.log('引用中的代码块')
 > 
 > 
+> 
+> 
 > ```
 
 ## 列表