Folders and files
| Name | Name | Last commit date | ||
|---|---|---|---|---|
markview 是一个在浏览器中打开 .md 文件并支持实时刷新的 Markdown 浏览工具。
如果你在使用 AI 编码助手或需要项目约束说明，请以 .github/copilot-instructions.md 为准。
- 支持 GitHub 风格 Markdown（表格、任务列表、脚注等）
- 代码高亮（Shiki）
- Mermaid 图表渲染
- LaTeX 数学公式（KaTeX）
深色 / 
浅色主题切换
文件分组管理
文档目录面板
平铺 / 
树形侧边栏（支持拖拽排序与文件搜索）- 思维导图与图谱视图：支持文档结构可视化与联动阅读定位
- YAML 前置元数据展示（可折叠元数据区域）
- MDX 支持（渲染 Markdown，去除 import/export，转义 JSX 标签）
宽版 / 
窄版阅读宽度切换
原始 Markdown 视图- 内置 Slides 演示模式（--- 分页、键盘翻页、全屏演示）
内容复制（Markdown / 文本 / HTML）
服务重启并保留会话- 自动会话备份与恢复
- 支持从操作系统文件管理器拖拽添加文件（内容以内存形式加载，拖拽文件不支持实时刷新）
- 对通过命令行打开的文件支持保存后实时刷新
Homebrew：
$ brew install kooksee/tap/markview手动安装：
从 发布页 下载对应平台二进制文件。
$ markview README.md # 打开单个文件
$ markview README.md CHANGELOG.md docs/*.md # 打开多个文件
$ markview spec.md --target design # 打开到指定分组markview 会在浏览器中展示 Markdown 内容，并在文件保存后自动刷新页面。
默认情况下，markview 在 6275 端口启动单个服务。
当同端口已存在 markview 服务时，后续命令不会重复启动进程，而是把新文件追加到已有会话中。
$ markview README.md # 后台启动 markview
$ markview CHANGELOG.md # 将文件追加到已运行服务如果你需要完全独立的会话，换一个端口即可：
$ markview draft.md -p 6276
可通过 --target（-t）把文件归入命名分组。每个分组对应一个 URL 路径与独立侧边栏。
$ markview spec.md --target design # 打开到 http://localhost:6275/design
$ markview api.md --target design # 追加到 design 分组
$ markview notes.md --target notes # 打开到 http://localhost:6275/notes
使用 --watch（-w）注册通配模式。匹配到的文件会自动打开，匹配目录也会被持续监听以发现新文件。
展开与自动发现会遵守项目内的 .gitignore（含嵌套规则），并始终跳过 .git/；通过命令行显式指定的文件不受此过滤。
$ markview --watch '**/*.md' # 递归监听并打开所有 .md
$ markview --watch 'docs/**/*.md' --target docs # 监听 docs 目录并放入 docs 分组
$ markview --watch '*.md' --watch 'docs/**/*.md' # 同时注册多个模式--watch 不能与文件参数同时使用。** 表示递归目录匹配。
使用 --unwatch 取消已注册模式。已添加进侧边栏的文件不会被自动移除。
$ markview --unwatch '**/*.md' # 取消默认分组中的模式
$ markview --unwatch 'docs/**/*.md' --target docs # 取消 docs 分组中的模式
$ markview --unwatch '/Users/you/project/**/*.md' # 按绝对路径取消模式会先解析为绝对路径再匹配，因此你可以使用相对路径，也可以使用 --status 输出中的绝对路径。
侧边栏支持平铺和树形两种视图：
 平铺 |
 树形 |
|---|---|
 |
 |
在文档右侧工具列点击 Slides 按钮即可进入演示模式。
- 使用 --- 分隔幻灯片（代码块内的 --- 不会被当作分页）
- 每次只渲染当前页，适合现场讲解
- 短封面页（仅标题，或标题 + 少量短文）会自动垂直居中
- 表格、图片、Mermaid / 代码块会按演示页尺寸缩放与排版
- 支持全屏演示与快捷键导航
示例：
# 封面
这是第一页
---
# 第二页
这是第二页常用操作：
| 操作 | 快捷键 / 交互 |
|---|---|
| 下一页 | → / PageDown / Space / Enter / 点击幻灯片空白区域 |
| 上一页 | ← / PageUp |
| 首/末页 | Home / End |
| 切换全屏 | F |
| 退出 | Esc（全屏时优先退出全屏，再次按下退出 Slides） |
| 固定/取消固定演示控件 | H |
Tip
全屏状态下，演示控件会在短暂无操作后自动隐藏；移动鼠标、触控或按键会再次显示。
markview 默认后台运行，命令会立即返回，不阻塞当前终端。
$ markview README.md
markview: serving at http://localhost:6275 (pid 12345)
$ # 终端可继续使用使用 --status 查看服务状态，使用 --shutdown 停止服务：
$ markview --status # 查看所有 markview 服务
http://localhost:6275 (pid 12345, v0.12.0)
default: 5 file(s)
watching: /Users/you/project/src/**/*.md, /Users/you/project/*.md
docs: 2 file(s)
watching: /Users/you/project/docs/**/*.md
$ markview --shutdown # 关闭默认端口服务
$ markview --shutdown -p 6276 # 关闭指定端口服务
$ markview --restart # 重启默认端口服务如果需要前台运行（例如调试时），可使用 --foreground：
$ markview --foreground README.md你可以点击页面右下角的 
重启按钮，或执行 markview --restart。
重启后会保留当前会话（分组与文件列表），适合在升级二进制后无缝切换到新版本。
markview 会在文件或模式发生变更时自动保存会话状态（按分组保存文件与监听模式）。
当服务再次启动时，会自动恢复上次会话，并与本次命令行参数合并（恢复项优先，新参数追加，去重处理）。
$ markview README.md CHANGELOG.md # 启动并打开两个文件
$ markview --shutdown # 关闭服务
$ markview # 恢复 README.md 与 CHANGELOG.md
$ markview TODO.md # 恢复会话并追加 TODO.md使用 --clear 可以清理某个端口的会话备份：
$ markview --clear # 清理默认端口备份
$ markview --clear -p 6276 # 清理指定端口备份使用 --json 可以将结果输出为结构化 JSON，便于脚本或自动化工具调用。
$ markview --json README.md
{
"url": "http://localhost:6275",
"files": [
{
"url": "http://localhost:6275/?file=a1b2c3d4",
"name": "README.md",
"path": "/Users/you/project/README.md"
}
]
}--status 也支持 --json：
$ markview --status --json
[
{
"url": "http://localhost:6275",
"status": "running",
"pid": 12345,
"version": "0.15.0",
"revision": "abc1234",
"groups": [
{
"name": "default",
"files": 3,
"patterns": ["**/*.md"]
}
]
}
]| 参数 | 简写 | 默认值 | 说明 |
|---|---|---|---|
| --target | -t | default | 分组名称 |
| --port | -p | 6275 | 服务端口 |
| --bind | -b | 0.0.0.0 | 绑定地址（如 localhost） |
| --open | 总是打开浏览器 | ||
| --no-open | 不自动打开浏览器 | ||
| --status | 查看运行中的 markview 服务 | ||
| --watch | -w | 监听通配模式（可重复） | |
| --unwatch | 移除已监听的模式（可重复） | ||
| --shutdown | 关闭运行中的 markview 服务 | ||
| --restart | 重启运行中的 markview 服务 | ||
| --clear | 清理指定端口的会话备份 | ||
| --foreground | 前台运行服务 | ||
| --json | 以 JSON 输出结构化结果 |
Warning
当 --bind 设置为非回环地址时，markview 会暴露到网络，且默认没有鉴权机制。远程客户端可能读取当前用户可访问文件、浏览通配目录并控制服务启停。该场景仅建议用于可信网络。
需要 Go 与 pnpm 环境。
$ make buildCI 中也提供独立构建产物流程：build-artifacts（GitHub Actions）。 该流程会使用 GoReleaser snapshot 模式构建多平台产物，并上传 dist 目录作为 workflow artifact，便于预发布验证。
项目发布使用 GoReleaser，支持两种方式：
- 自动发版：tagpr 在 main 生成新版本 tag，随后触发 release workflow 发布 GitHub Release。
- 手动发版：直接推送 v* tag（例如 v0.13.0），触发 release workflow。
本地可先做一次发布前验证（不真正发布）：
$ goreleaser release --snapshot --clean --skip=publish如果你需要导出离线讲稿（PDF/PPTX），仓库提供了 docs/slides/ 的 Marp 模板与主题，可通过 Makefile 预览和导出：
$ make slides-preview
$ make slides-pdf
$ make slides-pptx默认使用：
- docs/slides/tech-talk-template.md
- docs/slides/theme-markview.css
你也可以覆盖输入文件（示例）：
$ make slides-pdf SLIDES_FILE=docs/slides/my-talk.md更多模板说明见：docs/slides/README.md
为了便于本地阅读和二次开发，仓库提供了以下中文文档：
- 架构形态：Go 后端 + React 前端，最终以单二进制分发
- 运行机制：命令行单实例复用 + HTTP 接口 + 服务端事件流实时刷新
- 状态策略：服务端状态中心（groups/files/patterns）+ XDG 会话备份恢复
- 工程化：Makefile、CI（lint/test/coverage）、GoReleaser 多平台发布
| 中文称呼 | 代码中的常见写法 | 说明 |
|---|---|---|
| 命令行入口 | CLI | 指命令行程序入口与参数处理逻辑 |
| 接口 | API | 指前后端通过 HTTP 调用的内部接口 |
| 服务端事件流 | SSE | 用于将服务端变更实时推送到前端 |
| 监听模式 | watch pattern | 通过 --watch 注册的通配路径规则 |
| 前置元数据 | Frontmatter | Markdown 文件顶部的 YAML 元数据块 |
| 目录面板 | ToC | 文档标题目录导航面板 |
| 原文视图 | Raw | 直接查看 Markdown 原始文本 |
- yusukebe/gh-markdown-preview：在 GitHub 风格下预览 Markdown 的 GitHub CLI 扩展。
- MIT License
- 包含源码与 logo 在内的项目整体以 MIT 许可发布。
- logo 也可单独按 CC BY 4.0 使用。
- 在不修改 logo 且用于 markview 技术说明场景时，通常可不强制要求额外版权标注。
- Upstream: k1LoW/mo
- 上游许可：MIT（Copyright © 2026 Ken'ichiro Oyama）
- 归属与说明：见本仓库 NOTICE