yulonger/easy-slides
1
0
Fork 0
Code Issues Pull Requests Actions 3 Packages Projects Releases Wiki Activity
Files
924b1a15f3c026b7c2c728b812fae86ea365d6aa
easy-slides/README.md
T
yulonger 924b1a15f3
Engine CI / test (push) Waiting to run
Details
fix: make code block height content-aware
2026-08-31 20:08:32 +08:00

11 KiB
Raw Blame History

easy-slides engine

easy-slides 是一个独立的 Markdown 演示引擎，而不是演示内容仓库。它的关系更接近 GitBook：引擎可以通过 Git tag/commit 或 npm 包进行版本化，使用者在自己的 Git 仓库中维护配置、幻灯片和资源。

easy-slides engine repo
  ├─ @easy-slides/cli
  └─ slidev-theme-easy-jyy
             │ Git or npm dependency
             ▼
slides content repo
  ├─ easy-slides.config.mjs
  ├─ slides/<slug>/slides.md
  └─ .github/workflows/deploy-pages.yml
             │ easy-slides build
             ▼
        static dist/

本仓库只包含引擎、主题、测试和一个消费端示例。真正的课程、分享或博客演示应放在其他仓库。

在内容仓库中使用

创建新内容项目：

pnpm dlx @easy-slides/cli init my-slides
cd my-slides
pnpm install
pnpm dev -- welcome

已有仓库可以直接安装 CLI：

pnpm add -D @easy-slides/cli

不从 npm 发布或下载 easy-slides 包时，可以直接固定到引擎仓库的 tag 或 commit：

pnpm add -D '@easy-slides/cli@git+https://github.com/OWNER/easy-slides.git#v0.2.0'

私有仓库可以使用 SSH：

pnpm add -D '@easy-slides/cli@git+ssh://[email protected]/OWNER/easy-slides.git#COMMIT_SHA'

初始化一个同样使用 Git 依赖的内容仓库：

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：

{
  "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"
  }
}

内容仓库目录结构：

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。

项目配置

内容仓库根目录使用 easy-slides.config.mjs：

export default {
  title: 'Course Slides',
  description: '公开课程与技术分享',
  slidesDir: 'slides',
  outDir: 'dist',
  exportDir: 'exports',
}

配置、slides/ 和部署 Secret 都属于内容仓库。引擎升级只需要更新 @easy-slides/cli 版本。

每套演示位于 <slidesDir>/<slug>/slides.md。首页 frontmatter 的 title 必填，还支持 description、author、date、tags、cover 和 draft。

内容仓库命令

pnpm dev -- <slug|slides.md>
pnpm present -- <slug>
pnpm check
pnpm exec easy-slides install-browser
pnpm build
pnpm export -- <slug> --format pdf
pnpm export -- <slug> --format png
pnpm export -- <slug> --format pptx

dev 提供 VS Code/浏览器实时预览。present 监听局域网，打印观众地址、带同步密码的演示者二维码和手机遥控入口。build 扫描全部非 draft 演示，生成博客式首页与 /<slug>/ 静态站点。

build 的最终排版检查会启动引擎版本匹配的 Chromium。首次构建前运行 pnpm exec easy-slides install-browser；Linux CI 建议运行 pnpm exec easy-slides install-browser --with-deps，同时安装 Chromium 所需的系统依赖。easy-slides init 生成的 GitHub Pages workflow 已自动包含这一步，内容仓库不需要直接依赖或调用 playwright-chromium。

主题与演示能力

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：

---
layout: image-auto
image: ./assets/architecture.png
imagePlacement: auto
imageFit: contain
---

Markdown 图片默认保持比例并限制在内容区，也可以显式覆盖：

![架构图](./assets/architecture.png){fit="cover" position="50% 30%" max-height="65vh"}

主题默认使用 1024 × 768 的 4:3 画布。表格默认字号为 30px；代码默认字号为 28px，未指定高度时会按照内容使用自然高度，并根据前后正文自动限制在所在内容区内，长行会正常换行，超出后只上下滚动。需要按页调整时，在该页 frontmatter 中添加尺寸类：

---
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）。代码始终软换行并仅上下滚动。

只调整单个内容块时，可以使用 <div> 包裹 Markdown 内容：

<div class="easy-code-lg easy-code-height-sm">

```ts
const slides = await discover('slides')
```

</div>

同样的包裹方式也适用于表格，例如 <div class="easy-table-sm">。不添加固定高度类时，代码框保持内容的自然高度；内容较长时会自动扣除前后正文占用的空间并限制在内容区内。同一区域有多个代码框时也遵循这一规则。

公开放映页和演示者预览中的图片可以点击进入全屏预览，也可以聚焦图片后按 Enter 或空格打开；通过关闭按钮、点击背景或按 Esc 返回幻灯片。预览底部提供 − / 百分比 / + 工具栏，100% 对应图片原始像素尺寸；还可以使用鼠标滚轮、触控板或触屏双指缩放，并在放大后拖动查看细节，缩放范围为 10%–400%。

演示者点击图片时会优先在已连接的放映页打开；没有放映页确认时，图片在约半秒后回退到演示者页打开。演示者发起的同一轮预览会在所有放映页之间同步缩放、拖动和关闭；放映页自行点击打开的图片仍只影响本机。present 模式支持局域网跨设备联动，静态站点支持同一浏览器标签页联动。该交互不改变图片原始布局，也不会进入导出文件。

表格和代码块会在悬停或键盘聚焦时显示 − / 百分比 / + 缩放工具栏，可在 60%–160% 之间按 10% 调整；同一课件的放映页与演示者标签页会实时同步。代码缩放只改变字号，不改变高度或滚动位置。缩放只保存在当前页面内存中，刷新即恢复默认，也不会进入导出文件。

当一页内容超过 4:3 画布高度时，交互式放映页和演示者预览允许在幻灯片内部上下滚动，避免内容完全不可访问。滚动仅是兼容性兜底：pnpm dev 和 pnpm check 会直接解析 Slidev Markdown，在终端快速提示明显的静态溢出风险；开发期文件变化后只重新分析发生变化的页面，不启动浏览器，也不逐页访问预览路由。静态检查会按照 easy-jyy 的画布、布局、字号、表格、图片和显式代码高度估算容量，但不会伪造溢出像素；字体、异步组件、Mermaid、KaTeX 和自定义 CSS 的最终尺寸仍以 pnpm build 的浏览器渲染检查为准。构建检查会按课件、页码和标题打印真实纵向或横向溢出像素，发现问题也不会阻断构建。Web 页面本身不显示排版质量提示，导出、概览和打印仍保持固定画布；看到终端警告时应优先拆页、精简内容或调整字号。

动画、逐步显示、代码高亮和逐页演讲备注继续使用 Slidev 原生语法。

演示者 Token

Token 在内容仓库或部署平台中配置：

PRESENTER_TOKEN=a-long-non-obvious-token pnpm build

构建只写入 SHA-256 哈希。普通放映页不显示演示者入口；演示者通过 /presenter/ 或 easy-slides present 输出的专用地址进入。演示者页面未解锁时使用全局模态锁屏，背景控件、翻页快捷键和焦点均不可操作；正确 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 根包和主题包：

pnpm install
pnpm build
pnpm test
pnpm test:e2e
pnpm demo:dev -- getting-started
pnpm verify

推送 v* tag 会由引擎仓库的 release workflow 先发布主题、再发布 CLI；仓库 Secret NPM_TOKEN 仅属于引擎项目，与任何 slides 内容仓库无关。

发布 Git tag 前必须先运行 pnpm build 并提交生成的 dist-cli/。CI 会验证源码与这些预编译产物保持一致；这样内容仓库只需读取 Git 仓库，不需要在安装依赖时编译引擎。

视觉语言参考蒋炎岩老师的公开课程幻灯片，以及 MIT 许可的 jyyslide-md。

License

MIT

Reference in New Issue View Git Blame Copy Permalink