Markdown 禅模式预览。

本地 Markdown 预览服务器，支持热更新（HMR）、目录导航、代码高亮和 Admonition 语法块。

安装

# 全局安装（推荐）
npm install -g mdzen

# 或使用 pnpm
pnpm add -g mdzen

无需配置，安装后即可使用。

快速开始

在任意包含 .md 或 .mdc 文件的目录下运行：

mdzen

打开浏览器访问 http://localhost:3456，即可看到当前目录下所有 Markdown 文件的列表。

如何预览指定目录

使用 -d 选项指定文档根目录：

mdzen -d ./docs
mdzen -d /Users/me/notes

启动后访问 http://localhost:3456，左侧以树形结构展示所有 .md / .mdc 文件，点击即可预览。

如何使用自定义端口

默认端口为 3456，使用 -p 更换：

mdzen -d ./docs -p 8080

之后访问 http://localhost:8080。

如果端口已被占用，mdzen 会自动递增尝试下一个端口（最多 3 次）。

多实例管理

每个目录只能运行一个 mdzen 实例。同一目录重复启动时会提示已有实例并显示端口号。不同目录可以各自独立运行。

查看所有运行中的实例

mdzen list

输出示例：

当前运行的 mdzen 实例 (2 个):

  端口    PID     目录
  ────    ───     ──────
  3456    12345   /Users/me/docs
  3457    12346   /Users/me/notes

停止服务

# 停止当前目录的实例
mdzen stop

# 停止指定端口的实例
mdzen stop -p 3457

# 停止所有实例
mdzen stop --all

文档实时更新

保存 Markdown 文件后，浏览器中的内容会自动局部刷新，无需手动重载页面。右上角的绿色圆点表示连接状态：

| 颜色 | 含义 | | ---- | -------------------- | | 绿色 | 已连接，监听中 | | 黄色 | 正在更新内容 | | 红色 | 连接断开，自动重连中 |

Admonition 语法��

在 Markdown 中使用 ::: 语法插入高亮提示块：

:::info
这是一条普通信息。
:::

:::tip 最佳实践
可以在类型后面自定义标题。
:::

:::warning
操作前请注意备份。
:::

:::danger
此操作不可逆。
:::

支持的类型：info · tip · warning · danger · caution · note

Frontmatter 显示

文件顶部的 YAML frontmatter 会以结构化样式展示在正文上方：

---
title: 我的文档
author: Alice
draft: false
tags: guide, tutorial
---

正文内容...

boolean 值以绿/红徽章显示，逗号分隔的值以标签形式展示。

编辑器跳转

预览页面中，鼠标悬停在段落、标题等块级元素左侧会出现编辑按钮，点击可直接在 Cursor 中跳转到对应源码行。

CLI 参考

启动服务

mdzen [选项]

| 选项 | 默认值 | 说明 | | ------------ | -------- | ------------------------------------- | | -d <路径> | 当前目录 | 指��文档根目录（绝���路径或相对路径） | | -p <端口> | 3456 | 指定监听端口（被占用时自动递增） | | -h, --help | — | 显示帮助信息 |

子命令

| 命令 | 说明 | | ---------------------- | -------------------- | | mdzen list | 查看所有运行中的实例 | | mdzen stop | 停止当前目录的实例 | | mdzen stop -p <端口> | 停止指定端口的实例 | | mdzen stop --all | 停止所有实例 |

与同类工具对比

vs VSCode / Cursor 内置预览

| 维度 | 内置预览 | mdzen | | ---------- | -------------------- | ----------------------------------------- | | 预览窗口 | 编辑器分栏，空间受限 | 独立浏览器全屏，排版原汁原味 | | 多设备同步 | 不支持 | 本地 HTTP 服务，手机 / iPad 均可访问 | | 文件导航 | 无 | 树形文件列表 + 右侧 TOC，折叠状态持久化 | | 编辑器跳转 | 本身即编辑器 | 悬停块级元素 → 一键跳到 Cursor 对应源码行 |

vs Typora / Obsidian

| 维度 | Typora / Obsidian | mdzen | | ---------- | --------------------- | -------------------------------- | | 安装成本 | 独立安装 / 付费 | npm i -g mdzen 一行搞定 | | 运行方式 | 重量级 Electron | 纯 Node.js，内存占用极小 | | 文件绑定 | 私有格式 / vault 体系 | 读文件不改文件，零绑定 | | 多目录管理 | 需要建 vault | 任意目录即时启动，多实例互不干扰 |

vs grip / mdless 等 CLI 工具

| 维度 | grip | mdzen | | ---------- | --------------------------- | ---------------------------------- | | 网络依赖 | 调用 GitHub API，有频率限制 | 完全本地，离线可用 | | 实时热更新 | 需手动刷新 | SSE + HMR 局部替换，滚动位置不丢失 | | 样式 | 强绑定 GitHub 风格 | 深色 / 浅色主题，CSS 变量可扩展 | | admonition | 不支持 | 原生支持 :::tip :::warning 等 |

运行环境

• Node.js >= 18.0.0

许可证

ISC