From fef7459650204bb1f44ce2a9f500276676fa59fe Mon Sep 17 00:00:00 2001 From: yulonger's MacBook Pro 14 Date: Sat, 29 Aug 2026 19:00:23 +0800 Subject: [PATCH] docs: document engine usage and architecture --- README.md | 238 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 237 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 0d03def..4d61595 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,238 @@ -# easy-slides +# easy-slides engine +easy-slides 是一个独立的 Markdown 演示引擎，而不是演示内容仓库。它的关系更接近 GitBook：引擎可以通过 Git tag/commit 或 npm 包进行版本化，使用者在自己的 Git 仓库中维护配置、幻灯片和资源。 + +```text +easy-slides engine repo + ├─ @easy-slides/cli + └─ slidev-theme-easy-jyy + │ Git or npm dependency + ▼ +slides content repo + ├─ easy-slides.config.mjs + ├─ slides//slides.md + └─ .github/workflows/deploy-pages.yml + │ easy-slides build + ▼ + static dist/ +``` + +本仓库只包含引擎、主题、测试和一个消费端示例。真正的课程、分享或博客演示应放在其他仓库。 + +## 在内容仓库中使用 + +创建新内容项目： + +```bash +pnpm dlx @easy-slides/cli init my-slides +cd my-slides +pnpm install +pnpm dev -- welcome +``` + +已有仓库可以直接安装 CLI： + +```bash +pnpm add -D @easy-slides/cli +``` + +不从 npm 发布或下载 easy-slides 包时，可以直接固定到引擎仓库的 tag 或 commit： + +```bash +pnpm add -D '@easy-slides/cli@git+https://github.com/OWNER/easy-slides.git#v0.2.0' +``` + +私有仓库可以使用 SSH： + +```bash +pnpm add -D '@easy-slides/cli@git+ssh://git@github.com/OWNER/easy-slides.git#COMMIT_SHA' +``` + +初始化一个同样使用 Git 依赖的内容仓库： + +```bash +pnpm dlx 'git+https://github.com/OWNER/easy-slides.git#v0.2.0' \ + init my-slides \ + --engine 'git+https://github.com/OWNER/easy-slides.git#v0.2.0' +``` + +建议固定 tag 或完整 commit SHA，不要让生产部署长期跟随 `main`。引擎仓库会提交已经编译好的 `dist-cli/`，其中包含匹配版本的 JYY 主题；因此 Git 安装不需要运行 `prepare`，也不会再访问 npm 获取主题包。这同时避开了 pnpm 10/11 默认禁止 Git 依赖运行构建脚本的限制。 + +这里替代的是 easy-slides 自身的 npm 发布渠道。Slidev、Vue 等第三方依赖仍由 pnpm 按 lockfile 从 npm registry 安装；如果部署环境完全不能访问 registry，还需要配置镜像、缓存或额外做依赖 vendoring。 + +如果引擎仓库是私有的，Cloudflare Pages 或 GitHub Actions 还需要具备读取该 Git 仓库的 deploy key 或 access token。 + +推荐的 `package.json`： + +```json +{ + "private": true, + "scripts": { + "dev": "easy-slides dev", + "present": "easy-slides present", + "build": "easy-slides build", + "check": "easy-slides check", + "export": "easy-slides export" + }, + "devDependencies": { + "@easy-slides/cli": "^0.2.0" + } +} +``` + +内容仓库目录结构： + +```text +my-slides/ +├─ easy-slides.config.mjs +├─ package.json +├─ slides/ +│ ├─ operating-systems/ +│ │ ├─ slides.md +│ │ └─ assets/ +│ └─ concurrency/ +│ ├─ slides.md +│ └─ assets/ +└─ .github/workflows/deploy-pages.yml +``` + +可运行的完整消费端示例见 [examples/content-repo](./examples/content-repo)。 + +## 项目配置 + +内容仓库根目录使用 `easy-slides.config.mjs`： + +```js +export default { + title: 'Course Slides', + description: '公开课程与技术分享', + slidesDir: 'slides', + outDir: 'dist', + exportDir: 'exports', +} +``` + +配置、`slides/` 和部署 Secret 都属于内容仓库。引擎升级只需要更新 `@easy-slides/cli` 版本。 + +每套演示位于 `//slides.md`。首页 frontmatter 的 `title` 必填，还支持 `description`、`author`、`date`、`tags`、`cover` 和 `draft`。 + +## 内容仓库命令 + +```bash +pnpm dev -- +pnpm present -- +pnpm check +pnpm build +pnpm export -- --format pdf +pnpm export -- --format png +pnpm export -- --format pptx +``` + +`dev` 提供 VS Code/浏览器实时预览。`present` 监听局域网，打印观众地址、带同步密码的演示者二维码和手机遥控入口。`build` 扫描全部非 draft 演示，生成博客式首页与 `//` 静态站点。 + +## 主题与演示能力 + +CLI 会自动加载其版本匹配的 `slidev-theme-easy-jyy`，内容仓库不需要复制主题源码。 + +主题提供 `default`、`cover`、`center`、`section`、`quote`、`two-cols`、`image-auto`、`image-left`、`image-right` 和 `image-full` 布局，并统一处理代码、表格、引用、KaTeX、Mermaid、绘图和录制界面。 + +主题也内置课程与技术课件常用的内容样式：`compact`、`outline`、`current`、`lead`、`muted`、`course-table`、`source-figure`、`v-word` 和 `cover-identity`。内容仓库可直接使用这些类，不需要为每套演示复制相同的 `style.css`；只有真正属于单套演示的视觉差异才应放在演示目录的局部样式中。 + +`image-auto` 会在图片加载后读取真实宽高比：宽高比不小于 `1.6` 的图片采用“正文在上、图片在下”，其余图片采用“正文在左、图片在右”。需要锁定方向时使用 `imagePlacement: left|right|top|bottom`： + +```md +--- +layout: image-auto +image: ./assets/architecture.png +imagePlacement: auto +imageFit: contain +--- +``` + +Markdown 图片默认保持比例并限制在内容区，也可以显式覆盖： + +```md +![架构图](./assets/architecture.png){fit="cover" position="50% 30%" max-height="65vh"} +``` + +主题默认使用 `1024 × 768` 的 4:3 画布。表格默认字号为 `30px`；代码默认字号为 `28px`，未指定高度时会从当前位置自动延伸到所在内容区底部，长行会正常换行，超出后只上下滚动。需要按页调整时，在该页 frontmatter 中添加尺寸类： + +```md +--- +class: easy-table-lg easy-code-sm easy-code-height-md +--- +``` + +表格提供 `easy-table-sm`、`easy-table-md`、`easy-table-lg` 三档，字号与单元格留白会同步变化。代码字号提供 `easy-code-sm`、`easy-code-md`、`easy-code-lg` 三档；需要固定高度时可使用 `easy-code-height-sm`（180px）、`easy-code-height-md`（300px）、`easy-code-height-lg`（420px）。代码始终软换行并仅上下滚动。 + +只调整单个内容块时，可以使用 `
` 包裹 Markdown 内容： + +````md +
+ +```ts +const slides = await discover('slides') +``` + +
+```` + +同样的包裹方式也适用于表格，例如 `
`。不添加固定高度类时，单个代码框会占满标题或前置正文之后的剩余区域；同一区域有多个代码框时保持内容高度并限制在内容区内。 + +公开放映页和演示者预览中的图片可以点击进入全屏预览，也可以聚焦图片后按 `Enter` 或空格打开；通过关闭按钮、点击背景或按 `Esc` 返回幻灯片。演示者点击图片时会优先在已连接的放映页打开；没有放映页确认时，图片在约半秒后回退到演示者页打开。`present` 模式支持局域网跨设备联动，静态站点支持同一浏览器标签页联动。该交互不改变图片原始布局，也不会进入导出文件。 + +表格和代码块会在悬停或键盘聚焦时显示 `− / 百分比 / +` 缩放工具栏，可在 `60%–160%` 之间按 `10%` 调整；同一课件的放映页与演示者标签页会实时同步。代码缩放只改变字号，不改变高度或滚动位置。缩放只保存在当前页面内存中，刷新即恢复默认，也不会进入导出文件。 + +当一页内容超过 4:3 画布高度时，交互式放映页和演示者预览允许在幻灯片内部上下滚动，避免内容完全不可访问。滚动仅是兼容性兜底：`pnpm dev` 和 `pnpm check` 会直接解析 Slidev Markdown，在终端快速提示明显的静态溢出风险；开发期文件变化后只重新分析发生变化的页面，不启动浏览器，也不逐页访问预览路由。静态检查会按照 easy-jyy 的画布、布局、字号、表格、图片和显式代码高度估算容量，但不会伪造溢出像素；字体、异步组件、Mermaid、KaTeX 和自定义 CSS 的最终尺寸仍以 `pnpm build` 的浏览器渲染检查为准。构建检查会按课件、页码和标题打印真实纵向或横向溢出像素，发现问题也不会阻断构建。Web 页面本身不显示排版质量提示，导出、概览和打印仍保持固定画布；看到终端警告时应优先拆页、精简内容或调整字号。 + +动画、逐步显示、代码高亮和逐页演讲备注继续使用 Slidev 原生语法。 + +## 演示者 Token + +Token 在内容仓库或部署平台中配置： + +```bash +PRESENTER_TOKEN=a-long-non-obvious-token pnpm build +``` + +构建只写入 SHA-256 哈希。演示者页面未解锁时使用全局模态锁屏，背景控件、翻页快捷键和焦点均不可操作；正确 token 解锁后，状态保存在当前标签页的 `sessionStorage`，刷新保持，锁定或关闭标签页后失效。未设置 token 时，公开页面隐藏演示者入口，`check` 会提示警告。 + +这只是静态站点的便利门槛，不是服务端安全边界。备注和演示者代码仍可被技术用户分析。 + +## 部署内容仓库 + +Cloudflare Pages： + +- Build command：`pnpm build` +- Build output：`dist` +- Environment variable：`PRESENTER_TOKEN` +- 根路径部署不设置 `SITE_BASE` + +GitHub Pages：在内容仓库中加入示例里的 workflow，把 `PRESENTER_TOKEN` 保存为 Actions Secret。工作流将 `SITE_BASE` 设置为仓库名子路径。 + +## 开发引擎 + +本仓库使用 pnpm workspace，包含 CLI 根包和主题包： + +```bash +pnpm install +pnpm build +pnpm test +pnpm test:e2e +pnpm demo:dev -- getting-started +pnpm verify +``` + +- CLI 源码：[scripts](./scripts) +- JYY 主题：[packages/slidev-theme-easy-jyy](./packages/slidev-theme-easy-jyy) +- 外部内容仓库示例：[examples/content-repo](./examples/content-repo) + +推送 `v*` tag 会由引擎仓库的 release workflow 先发布主题、再发布 CLI；仓库 Secret `NPM_TOKEN` 仅属于引擎项目，与任何 slides 内容仓库无关。 + +发布 Git tag 前必须先运行 `pnpm build` 并提交生成的 `dist-cli/`。CI 会验证源码与这些预编译产物保持一致；这样内容仓库只需读取 Git 仓库，不需要在安装依赖时编译引擎。 + +视觉语言参考蒋炎岩老师的公开课程幻灯片，以及 MIT 许可的 [jyyslide-md](https://github.com/zweix123/jyyslide-md)。 + +## License + +MIT