泽尔普

zerp 是一个零配置显示框架。 幻灯片可以在HTML,Markdown中被编写出,或者两者的混合.

每个演示文稿都可以作为 slides/ 文件夹 :

my-deck/
  slides/
    00-title.html
    10-intro.md
    20-content.md
    images/
      cover.jpg

zerp 发现 slides/**/*.html 财务报告和审定财务报表 slides/**/*.md,按文件名排序,重写相对资产 URL,使幻灯片本地资产继续工作,注入默认样式/运行时间,并服务或构建一页甲板。 字体被捆绑在输出中,所以一个已建成的甲板是一个自成一体的文件,呈现出全线下.

维护者政策

我用这个 zerp 所以我才把它作为免费的开源软件公开.

这并不意味着我可以进行一般性合作。 问题和牵引请求被故意取消。 我没有能力免费调试别人的问题,我不想花时间去分解低信号或AI生成的贡献.

如果你想把项目当作是,请做。 如果您需要固定、功能或帮助将其融入工作流程,请直接联系我获取付费支持.

使用量

从本地检出中安装 :

pnpm add -D file:../zerp
pnpm exec zerp serve .

或从登记处:

pnpm add -D @emirotin/zerp
pnpm exec zerp build .

图标 :

pnpm exec zerp serve                      # serve the current deck on http://localhost:8000 (live-reloads on save)
pnpm exec zerp serve . 3000 --theme dark  # explicit deck dir, port, default theme
pnpm exec zerp build --theme light        # write ./index.html (light default)
pnpm exec zerp check                      # browser-backed contrast, font-size, glyph, frame/layout report (both themes, the deck's design size; --theme dark|light|both, --size WxH, --only category,..., --json for tooling)
pnpm exec zerp print -o deck.pdf          # render straight to PDF at the deck's design size
pnpm exec zerp slides                     # deck position → source file mapping (--json for tooling)

浏览器

zerp check 在真实的无头浏览器中打开每个主题,并需要一个Chromium级一. 它从来不捆绑一个——它按此顺序解决一个外部浏览器:

1. CHROME_BIN - 如果设定,它会赢。 指向任意 Chrome/ Chromium 二进制—— 绝对路径或命令名称 PATH; 执行带有额外旗帜的包装脚本也有效, 只要它能回答 --version 与浏览器的版本横幅相通. 这个标语是健康检查:在路上的非浏览器在这里是一个明显的错误,而不是后来令人困惑的发射失败.
2. 剧作家管理的Chrimium - 运行 zerp install-browser 一次下载; 之后不需要其他配置 .
3. 系统铬/铬 – Google Chrome 或 Chromium 在通常的 macOS 应用路径或上找到 PATH (单位:千美元)google-chrome, (中文(简体) ), chromium, (中文(简体) ), chromium-browser) (中文(简体) ). 发现于 PATH 在启动前,每个候选人必须回答 --version 使用一个版本的横幅,所以一个非浏览者 蹲在其中一个名字上(Ubuntu的快速过渡) chromium 跳过而不是撞上发射.

如果没有找到, zerp check {\fn黑体\fs22\bord1\shad0\3ahbe\4ah00\fscx67\fscy66\2chffffff\3ch808080}说到这里和点数 zerp build构建后检查摘要打印出一行通知并持续而非失败). 在没有系统Chrome的机器上,安装一次:

pnpm exec zerp install-browser   # download the managed Chromium
# — or —
export CHROME_BIN="/path/to/chrome"

浏览器保持外部和可选性:包本身是无浏览器的,因此安装是轻而易举的和离线的.

重用运行中的浏览器

默认每个 zerp check 发射浏览器并再次关闭。 反复检查甲板的主机——CI,一个服务,一个手表回路——可以保持一个浏览器的温度取而代之,并用指针检查它 --browser-endpoint url (或 ZERP_BROWSER_ENDPOINT:

# CDP: any Chrome started with --remote-debugging-port
pnpm exec zerp check --browser-endpoint http://127.0.0.1:9222
# playwright protocol: an endpoint from chromium.launchServer()
pnpm exec zerp check --browser-endpoint ws://127.0.0.1:5000/<guid>

偏爱 http(s):// (CDP)当主机运行自己的剧作家建设时:它是浏览器自己的协议,因此双方不需要共同的版本. ws(s):// 说出剧作家协议,该协议在客户端和服务器之间进行版本锁定.

提供浏览器属于谁启动它:检查创建了自己的上下文,关闭了上下文,断开——它从不关闭浏览器. 在此模式下不需要或查找本地浏览器 。 主机在检查运行时必须保持事件循环响应;一个阻断它的主机(一个同步的子进程呼叫,比如)可以拖住它借出的那个浏览器.

工具

这个回波通过 Volta 元数据将节点和pnpm 标出 package.json数字 :

volta pin [email protected] [email protected]

质量命令 :

pnpm lint
pnpm lint:fix
pnpm format
pnpm format:check
pnpm test:browser # opt-in headless-browser regression test (requires Chrome/Chromium)

husky 运行 lint-staged 每个人承诺前都要检查建筑. dist/ 不被检查为 git; 它是按要求构建的,并通过 npm 包包含在内 prepublishOnly。 。 。 .

撰写

• 将所有作者内容放入 slides/。 。 。 .
• 命令使用文件名前缀, 例如 00-, (中文(简体) ), 10-, (中文(简体) ), 20-。 。 。 .
• 甲板资产 slides/ 我也一样。 相对链接如 src="./images/foo.jpg" 自动重写.
• 每个 .html 文件可以包含一个或多个 <div class="slide"> 块.
• .md 文件也被支持。 每个 Markdown 文件自动被包入 <div class="slide"> 在建设时间——不需要手动包装。 使用 --- 以在单行内分离多个幻灯片 .md 文档.
• Markdown文件中的 Raw HTML 未改变通过, 因此可以嵌入交互式 <script> 块, 自定义 <div> 版式,或 <style> 元素与 Markdown 内容.
• 在建设时间,每一个真实 .slide 放在一个框架拥有的 <div data-zerp-slide>。框架控制可见度;内部 .slide 是完整大小的布局表面,所以自定义根可能使用 display: grid 或另一种安全布局。 不给保留框架属性设置样式 .
• 框架默认 CSS 和浏览器运行时间作为单独的源资产存储,并在生成的 HTML 中内入 serve 财务报告和审定财务报表 build。 。 。 .
• 颜色来自设计符号(var(--zerp-*)由和谐调色板生成;甲板以暗淡的主题渲染. 不要硬码颜色 .
• 页面标题来自第一个幻灯片的上行标题(通过 title 构建选项;文件夹名称为倒置).
• 运行 zerp check 在作者之后,并在任何布局变化之后: 它以无头 Chrome/ Chromium 打开每个主题(按下面描述的解开) 浏览器 - 运行 zerp install-browser 如果您没有系统 Chrome ) , 并报告, 每张幻灯片, WCAG 2. x 对比度, 字体大小的地板, 表面宽度, glyph/ font- fount- fall 覆盖度, SVG 文本被封禁, 以及 — 排版侧面, 从前者折叠 zerp verify ——完全一个全尺寸的幻灯片框架是活动并可见的,没有页面溢出,加上任何浏览器控制台出错. 超流是相对于已检查的取景口——甲板已宣布 zerp.size,或1920x1080,如果它宣布无,除非 --size WxH 超过它;摘要和 --json是因为 viewport 区域(包括其 source数字 : "deck", (中文(简体) ), "default",或 "flag"准确记录检查的内容. zerp check 需要浏览器; 没有它来命名问题( 没有找到浏览器, 或者 CHROME_BIN 指向无效的地方)和指向 zerp install-browser。 。 。 .
• 每个发现都带有 category - 其中一个 contrast, (中文(简体) ), type-size, (中文(简体) ), surface, (中文(简体) ), glyph, (中文(简体) ), svg-text, (中文(简体) ), frame, (中文(简体) ), overflow, (中文(简体) ), safe-zone, (中文(简体) ), console ——在其报告行前印出. --only category,category 将运行缩小为逗号分隔子集;用完整列表拒绝未知的分类.
• 每个甲板内嵌了字体:一个建筑物载有蒙特塞拉特和Roboto Mono子集 unicode-range 甲板本身的文字实际上触动(拉丁语总是),加上一个一格文字面来表示 →因此,不使用西里尔字母的一副拉廷甲板,以及按类型划分的甲板 № 船的子集 覆盖它.
• zerp check'glyph finding names, each mention, its text by a font jadle 不捆绑, 以及倒回家族—— 例如, 堆栈 serp 中的元素集没有子集它包含的字符 。 造型器本身是真理的来源:泽尔普将所运载的每个字体都刻入其中 @font-face,因此Chrome自己对"什么字体真正地画了这个glyph"的回答(Chrome)isCustomFont: false)是报告的内容,不是静态覆盖表. 归宿是每个元素,而不是每个代码点或计数——当父母的倒背格莱比特是同家族中后代的子集时,发现地在后人上;滑行仍然被标出,只有元素指针是相接地. Emoji被豁免——每个平台都从自己的彩色Emoji字体中取出. llms.txt 文档完整的边缘大小写(ZWJ序列,生成的内容, <svg> 页:1.
• zerp check --safe-margin px 另外要求每张幻灯片的每个顶层元素至少保持所有页边中的多个px——一个指向PDF的甲板的打印安全设置. 故意用 data-zerp-bleed 以豁免他们。 默认关闭; 选择幻灯片粘贴下方的边距, 普通内容从不移动 .
• zerp check --timeout ms (或 ZERP_VERIFY_TIMEOUT_MS)设定整个浏览器会话的预算——启动,导航,字体活化和探测. 默认为20000ms,适合开发者机器;在小型或装入的宿主上起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起起 预算用完的会话完全不产生报告,所以如果自动化 zerp check,给它一个预算,与它运行的宿主匹配,并将超时作为失败的检查而不是通过检查.
• 设计师的风格指南 docs/style-system.pdf (可解决为 @emirotin/zerp/docs/style-system.pdf:分层,类型对等,两个主题中的符号表,公用设施,以及每个组件,都有框架自己样式表提供的所有实例. 它从当前样式表重印到每个版本,所以它描述了您安装的版本.
• "Slide N"指基于1的甲板位置(屏幕上计数器显示的内容)——文件前缀只命令文件. zerp slides 打印位置 ~ 文件映射; 按 s 显示活动幻灯片的来源.

打印和 PDF 导出

pnpm exec zerp print                      # write ./index.pdf at the deck's design size
pnpm exec zerp print . --theme dark -o out.pdf

zerp print 是条犬形路径: 它使甲板直接变成 PDF 其设计尺寸zerp.size,或1920×1080,如果甲板宣布无) 无头浏览器,没有手动取景口或页面大小的设置. 它能产生 一个 每张幻灯片的页面 按甲板顺序排列: 演示文稿铬(导航、计数器、进度) 栏,主题切换,源徽章) 被隐藏,并按其 最终状态——每 data-step 显示, 每一个 data-until-step 元素 不见了。 溢出幻灯片的内容被剪贴在页面底部 而不是溢出到第二页,所以在框内保持滑动( 和屏幕上一样 zerp check 渔获量溢出).

任何建筑 index.html 也可以按原样打印(浏览器打印对话框,或 无头打印后端),用于自定义管线,比需要更多的控制 zerp print 提供。 打印为 a 页面大小等于演示文稿 视图 并启用背景 —— 一个幻灯片在任意一页完全填充 页面大小,任一主题。 示例:在1920x1080年将甲板制成PDF 直接播放剧作家 :

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch()
    page = browser.new_page(viewport={"width": 1920, "height": 1080})
    page.goto("file:///abs/path/to/index.html")
    page.pdf(path="deck.pdf", width="1920px", height="1080px", print_background=True)
    browser.close()

明确 width编号 :height 已描述页面 – do 没有 也通过 landscape=True,因为铬交换了两个维度 landscape 实值 设定并获得一个肖像页.

地标配置( 可选)

甲板不需要配置:带有 slides/ 是一个甲板。 两者 它不能表达的东西是 它被设置在什么类型面 设计大小, 所以可选 zerp 在甲板上的密钥 package.json 可以命名它们 :

{
  "dependencies": {
    "@fontsource/bebas-neue": "^5",
    "@fontsource/inter": "^5",
    "@fontsource/jetbrains-mono": "^5"
  },
  "zerp": {
    "size": "1920x1080",
    "fonts": {
      "display": { "family": "Bebas Neue", "weights": ["400"] },
      "body": { "family": "Inter" },
      "mono": { "family": "JetBrains Mono" }
    }
  }
}

• size 实值 "WxH" 在 CSS 像素中。 未设定, 它默认为 1920x1080它会修正 甲板的设计帆布——每个滑动相框都大小到它和运行时间 缩放可与真实浏览器窗口相匹配的缩放 —— 双倍于 默认视图端口 zerp check 对照措施和页数 zerp print 生产,所以所有三个 保持锁步 不重复数字在 命令行.
• family 是字体声明的名称, 与您要输入的名称相同 font-family泽尔普对照包裹检查,如果两者不同,会这么说.
• fontsourcePackage 是可选的;默认为 @fontsource/<family> 斜体化 ("JetBrains Mono" → @fontsource/jetbrains-mono) (中文(简体) ).
• 甲板本身安装了包. zerp从甲板解决它 node_modules (倒回自己的),所以 pnpm add @fontsource/inter 在建筑之前。 无法解决的软件包是构建错误命名 软件包和安装命令.
• weights 是可选的, 默认为 zerp 自己样式要求的: 身体 400 600 700 900 400-italic单 400 700 (fontsource file Braw). 互联网档案馆的存檔,存档日期2013-12-21. 重量 一个家庭不会飞来飞去.
• display 设置面额为 h1。未设置,它遵循 body 家庭,包裹 和重量,所以甲板只命名 body 到处找家人.
• mono 未设定保留 Roboto Mono; 从未遵循 body因为导航系统, 代码,表格和标签需要真正的单相空间度量.
• 显示面相适用于 h1 只有这个 将其他人从您自己移动到它上 样式表 - h2 { font-family: var(--zerp-font-display) } - 或者关闭它与 h1 { font-family: var(--zerp-font-body) }zerp的规则为零 特异性使纯元素选择器获胜.
• 子集仍然被甲板的文本所选择,所以一个CJK家族被携带了几个 范围在一个时间而不是所有的时间.
• 其他一切不变: → 脸总是被捆绑,每个家庭 保持它的作用 在五堆泽尔普绘图.

图书馆 API

import { buildPresentationHtml, writePresentation } from "@emirotin/zerp";

示例

此寄存器包括一个迁移到 examples/casino/。其作者来源仅是 examples/casino/slides/。 。 。 .