Sprint/3

Makefile

@@ -2,16 +2,30 @@ PKG = github.com/kooksee/markview
 COMMIT = $(shell git rev-parse --short HEAD)
 
 BUILD_LDFLAGS = "-s -w -X $(PKG)/version.Revision=$(COMMIT)"
+MARP = pnpm dlx @marp-team/marp-cli
+SLIDES_FILE ?= docs/slides/tech-talk-template.md
+SLIDES_THEME ?= docs/slides/theme-markview.css
+SLIDES_PDF ?= docs/slides/tech-talk-template.pdf
+SLIDES_PPTX ?= docs/slides/tech-talk-template.pptx
 
 default: test
 
 ci: depsdev generate test
 
+slides-preview:
+	$(MARP) $(SLIDES_FILE) --theme-set $(SLIDES_THEME) --preview
+
+slides-pdf:
+	$(MARP) $(SLIDES_FILE) --theme-set $(SLIDES_THEME) --pdf -o $(SLIDES_PDF)
+
+slides-pptx:
+	$(MARP) $(SLIDES_FILE) --theme-set $(SLIDES_THEME) --pptx -o $(SLIDES_PPTX)
+
 generate:
 	go generate ./internal/static/
 
 test:
-	cd frontend && pnpm install && pnpm run test:coverage
+	cd frontend && sh scripts/pnpm-install-safe.sh && pnpm run test:coverage
 	go test ./... -coverprofile=coverage.out -covermode=count -count=1
 
 build: generate
@@ -27,15 +41,15 @@ screenshot: build
 	cd frontend && pnpm run screenshots
 
 lint:
-	cd frontend && pnpm install && pnpm run lint
+	cd frontend && sh scripts/pnpm-install-safe.sh && pnpm run lint
 	golangci-lint run ./...
 	go vet -vettool=`which gostyle` -gostyle.config=$(PWD)/.gostyle.yml ./...
 
 fmt:
-	cd frontend && pnpm install && pnpm run fmt
+	cd frontend && sh scripts/pnpm-install-safe.sh && pnpm run fmt
 
 fmt-check:
-	cd frontend && pnpm install && pnpm run fmt:check
+	cd frontend && sh scripts/pnpm-install-safe.sh && pnpm run fmt:check
 
 depsdev:
 	go install github.com/Songmu/gocredits/cmd/gocredits@latest
@@ -51,4 +65,4 @@ credits: depsdev generate
 prerelease_for_tagpr: credits
 	git add CHANGELOG.md CREDITS go.mod go.sum
 
-.PHONY: default ci generate test build dev screenshot lint fmt fmt-check depsdev credits prerelease_for_tagpr
+.PHONY: default ci generate test build dev screenshot lint fmt fmt-check depsdev credits prerelease_for_tagpr slides-preview slides-pdf slides-pptx

README.md

@@ -33,6 +33,7 @@
 - MDX 支持（渲染 Markdown，去除 `import`/`export`，转义 JSX 标签）
 - <img src="images/icons/width-expand.svg" width="16" height="16" alt="宽布局"> 宽版 / <img src="images/icons/width-compress.svg" width="16" height="16" alt="窄布局"> 窄版阅读宽度切换
 - <img src="images/icons/raw.svg" width="16" height="16" alt="原文"> 原始 Markdown 视图
+- 内置 Slides 演示模式（`---` 分页、键盘翻页、全屏演示）
 - <img src="images/icons/copy.svg" width="16" height="16" alt="复制"> 内容复制（Markdown / 文本 / HTML）
 - <img src="images/icons/restart.svg" width="16" height="16" alt="重启"> 服务重启并保留会话
 - 自动会话备份与恢复
@@ -124,6 +125,42 @@ $ markview --unwatch '/Users/you/project/**/*.md'            # 按绝对路径
 | ------------------------------------------------------- | ------------------------------------------------------- |
 | ![平铺视图](images/sidebar-flat.png)                    | ![树形视图](images/sidebar-tree.png)                    |
 
+### 内置 Slides 演示模式
+
+在文档右侧工具列点击 `Slides` 按钮即可进入演示模式。
+
+- 使用 `---` 分隔幻灯片（代码块内的 `---` 不会被当作分页）
+- 每次只渲染当前页，适合现场讲解
+- 支持全屏演示与快捷键导航
+
+示例：
+
+```md
+# 封面
+
+这是第一页
+
+---
+
+# 第二页
+
+这是第二页
+```
+
+常用操作：
+
+| 操作                  | 快捷键 / 交互                                             |
+| --------------------- | --------------------------------------------------------- |
+| 下一页                | `→` / `PageDown` / `Space` / `Enter` / 点击幻灯片空白区域 |
+| 上一页                | `←` / `PageUp`                                            |
+| 首/末页               | `Home` / `End`                                            |
+| 切换全屏              | `F`                                                       |
+| 退出                  | `Esc`（全屏时优先退出全屏，再次按下退出 Slides）          |
+| 固定/取消固定演示控件 | `H`                                                       |
+
+> [!TIP]
+> 全屏状态下，演示控件会在短暂无操作后自动隐藏；移动鼠标、触控或按键会再次显示。
+
 ### 启动与停止
 
 `markview` 默认后台运行，命令会立即返回，不阻塞当前终端。
@@ -250,6 +287,29 @@ $ markview --status --json
 $ make build
 ```
 
+## 可选：Markdown PPT 导出（Marp）
+
+如果你需要导出离线讲稿（PDF/PPTX），仓库提供了 `docs/slides/` 的 Marp 模板与主题，可通过 Makefile 预览和导出：
+
+```console
+$ make slides-preview
+$ make slides-pdf
+$ make slides-pptx
+```
+
+默认使用：
+
+- `docs/slides/tech-talk-template.md`
+- `docs/slides/theme-markview.css`
+
+你也可以覆盖输入文件（示例）：
+
+```console
+$ make slides-pdf SLIDES_FILE=docs/slides/my-talk.md
+```
+
+更多模板说明见：`docs/slides/README.md`
+
 ## 中文文档
 
 为了便于本地阅读和二次开发，仓库提供了以下中文文档：

docs/markdown-capabilities.md

@@ -63,6 +63,11 @@
 - ToC 面板（按 H1-H6 标题导航）
 - 当前标题高亮与平滑滚动定位
 - 原文视图（Raw）与渲染视图切换
+- Slides 演示视图（按 `---` 分页，代码块内分隔线自动忽略）
+  - 支持按钮翻页与键盘翻页（`←/→`、`PageUp/PageDown`、`Space/Enter`、`Home/End`）
+  - 支持 `F` 全屏、`Esc` 退出（全屏时优先退出全屏）
+  - 支持点击幻灯片空白区域下一页
+  - 全屏下支持演示控件自动隐藏与 `H` 固定/取消固定
 - 全局全文搜索后可跳转到目标文档并定位命中内容
 
 ## 4. 结构化关系能力

docs/quick-start-visual.md

@@ -35,6 +35,16 @@ $ markview -p 16275 -b localhost --no-open testdata/basic.md testdata/mermaid-fl
 - 图表块支持缩放/全屏等交互（不同图表能力略有差异）
 - 目录、原文、复制、导出等按钮在文档右侧工具列
 
+### 2.1 快速体验内置演示模式（Slides）
+
+在任意 Markdown 文档右侧点击 `Slides` 按钮即可进入演示模式：
+
+- 使用 `---` 进行分页（代码块内 `---` 不会触发分页）
+- `F` 切换全屏，`Esc` 退出（全屏时先退全屏）
+- 可用 `←/→`、`Space`、`PageUp/PageDown` 翻页
+- 点击幻灯片空白区域也可进入下一页
+- 全屏下控件会自动隐藏；`H` 可固定/取消固定控件
+
 ## 3) 体验结构可视化模式
 
 在页面顶部工具栏点击图谱相关按钮：

docs/slides/README.md

@@ -0,0 +1,39 @@
+# Markdown PPT（Marp）模板
+
+本目录提供一套可直接开讲的 Marp 幻灯片模板。
+
+## 文件说明
+
+- `tech-talk-template.md`：演示模板（16:9、分页、结构化内容）
+- `theme-markview.css`：深色中文主题
+
+## 本地预览
+
+在仓库根目录执行：
+
+make slides-preview
+
+## 导出 PDF
+
+make slides-pdf
+
+## 导出 PPTX
+
+make slides-pptx
+
+## 自定义输入文件
+
+make slides-preview SLIDES_FILE=docs/slides/my-talk.md
+make slides-pdf SLIDES_FILE=docs/slides/my-talk.md SLIDES_PDF=docs/slides/my-talk.pdf
+make slides-pptx SLIDES_FILE=docs/slides/my-talk.md SLIDES_PPTX=docs/slides/my-talk.pptx
+
+## 不走 Makefile（可选）
+
+pnpm dlx @marp-team/marp-cli docs/slides/tech-talk-template.md --theme-set docs/slides/theme-markview.css --preview
+
+## 快速改造建议
+
+1. 先改标题页与目录页
+2. 每页只放一个核心观点
+3. 一页最多 5~7 条要点
+4. 代码页只展示最关键片段

docs/slides/tech-talk-template.md

@@ -0,0 +1,112 @@
+---
+marp: true
+theme: markview
+paginate: true
+size: 16:9
+footer: 'markview · 技术分享模板'
+---
+
+<!-- _class: lead -->
+
+# 标题：你的主题
+
+### 副标题（可选）
+
+**演讲者**：你的名字  
+**日期**：2026-05-11
+
+---
+
+## 今天你将听到什么
+
+1. 背景与问题
+2. 核心方案
+3. 关键实现
+4. 实验结果
+5. 下一步计划
+
+---
+
+## 背景与问题
+
+- 现状：一句话描述当前场景
+- 痛点：列 2~3 个关键问题
+- 目标：明确可衡量目标（如耗时、成功率、体验）
+
+> 建议：每页只讲一个主观点。
+
+---
+
+## 方案总览
+
+- 方案 A：最小可行，先跑通
+- 方案 B：工程化增强，降低长期成本
+- 取舍：开发速度 vs 维护复杂度
+
+| 方案 | 开发成本 | 维护成本 | 推荐      |
+| ---- | -------- | -------- | --------- |
+| A    | 低       | 中       | ✅         |
+| B    | 中       | 低       | ✅（迭代） |
+
+---
+
+## 关键实现（代码示例）
+
+```ts
+interface BuildOptions {
+  platform: string;
+  arch: string;
+}
+
+export function resolveRuntimeKey(opts: BuildOptions): string {
+  return `${opts.platform}-${opts.arch}`;
+}
+```
+
+- 把复杂逻辑封装成可测试函数
+- 优先让失败可观测（日志/错误信息）
+
+---
+
+## 效果对比
+
+- 改造前：偶发失败、跨设备不稳定
+- 改造后：自动自愈、重复执行稳定
+
+**关键收益**
+
+- 交付稳定性提升
+- 切机/换架构成本下降
+- 团队协作摩擦减少
+
+---
+
+## 风险与边界
+
+- 边界 1：网络异常导致依赖下载失败
+- 边界 2：锁文件版本漂移
+- 边界 3：本地缓存污染
+
+**应对策略**
+
+- 明确重试与回滚策略
+- 固定关键版本
+- 保留一键修复入口
+
+---
+
+## 下一步计划
+
+- [ ] 增加 CI 校验
+- [ ] 补齐回归测试
+- [ ] 增加文档与操作手册
+
+<small>Tip：最后一页最好给出明确的行动项。</small>
+
+---
+
+<!-- _class: lead -->
+
+# Q & A
+
+谢谢大家 🙌