Sensei 镜像文档

镜像概述和主要用途

Sensei 是训练材料的编译器，主要用于生成 PDF 文档以及提供幻灯片和实验内容的 Web 服务，可替代 zenika-formation-framework。它提供命令行工具，支持通过 Docker 容器或 Node.js 环境运行，适用于培训材料的制作、展示与分发场景。

核心功能和特性

• PDF 生成：将包含幻灯片（Slides）和工作手册（Workbook）的训练材料编译为 PDF 文件
• Web 服务：提供幻灯片和实验内容的在线访问服务，支持本地浏览器预览
• CLI 工具：通过命令行界面操作，支持 pdf（生成PDF）、serve（启动服务）等命令
• 兼容性：支持 Reveal.js 幻灯片（含 Markdown、Highlight 等插件）和 Markdown 工作手册编写
• 跨平台：可在 Docker 环境中运行，兼容 Windows（WSL2）、Linux 和 macOS 系统

使用场景和适用范围

适用于培训材料制作与展示场景，包括：

• 培训讲师生成标准化的 PDF 培训手册
• 在线展示培训幻灯片和实验指导内容
• 培训材料开发者编写、预览和测试课程内容

详细的使用方法和配置说明

安装方式

使用已发布的 Docker 镜像 🐳

1. 拉取镜像：

   shell
   docker image pull zenika/sensei
   

2. 创建 sensei 命令别名：

   shell
   alias sensei='docker container run \
     --pull always \
     --interactive \
     --tty \
     --rm \
     --volume $(pwd):/$(basename $(pwd)) \
     --workdir /$(basename $(pwd)) \
     --publish ${SENSEI_PORT:-8080}:${SENSEI_PORT:-8080} \
     --env SENSEI_PORT \
     --cap-add=SYS_ADMIN \
     zenika/sensei'
   

⚠ 在 Docker 容器中运行时，--material 参数仅限工作目录的子目录。

⚠ 如需修改端口，使用以下方式：export SENSEI_PORT=9000; sensei（详见 相关说明）。

Windows 系统 Docker 使用注意事项

在 Windows 中使用 WSL2 运行 Docker 时，建议将文件存储在 Linux 文件系统（WSL2 内部），可通过 \\wsl$\（或 \\wsl.localhost\）从 Windows 访问。使用 VSCode 时，可通过 WSL 扩展 编辑文件。

⚠ 使用 Windows 文件系统时，培训内容修改后的热重载功能可能失效。 ⚠ 在 Git Bash 中使用时，需修改 --volume 和 --workdir 路径格式：--volume /$(pwd):/$(basename $(pwd)) --workdir //$(basename $(pwd)（避免路径错误）。

从源码构建 Docker 镜像 🐳

1. 克隆仓库并进入目录：

   shell
   git clone [***]
   cd sensei
   

2. 构建镜像：

   shell
   docker image build --tag zenika/sensei ./
   

3. 创建别名（移除 --pull always 参数）：

   shell
   alias sensei='docker container run \
     --interactive \
     --tty \
     --rm \
     --volume $(pwd):/$(basename $(pwd)) \
     --workdir /$(basename $(pwd)) \
     --publish ${SENSEI_PORT:-8080}:${SENSEI_PORT:-8080} \
     --env SENSEI_PORT \
     --cap-add=SYS_ADMIN \
     zenika/sensei'
   

⚠ 同样适用上述 Docker 运行警告。

使用 Node.js 安装

shell
npm install --global [***]

⚠ Yarn 可能存在缓存问题，导致更新失败，建议使用 npm。

使用方法

查看帮助

shell
sensei --help

生成 PDF

1. 进入训练材料目录（需包含 Slides/slides.json 和 Workbook/workbook.json）：

   shell
   cd /path/to/training-material
   

2. 运行生成命令：

   shell
   sensei pdf
   

3. 生成的 PDF 文件将保存在 pdf 目录下。

提供幻灯片和实验内容的 Web 服务

1. 进入训练材料目录：

   shell
   cd /path/to/training-material
   

2. 启动服务：

   shell
   sensei serve
   

3. 在浏览器中访问 http://localhost:8080/ 查看内容。

材料编写指南

幻灯片

采用 Reveal.js 格式编写，支持 Reveal.js 文档 中的功能。已启用插件：Markdown、Highlight、Zoom、Notes、Math。

工作手册

采用 Markdown 格式编写。

ℹ 使用 <!-- toc --> 可在指定位置插入目录。

开发指南

运行

1. 安装依赖：

   shell
   npm i
   

2. 运行 CLI（指向训练材料目录）：

   shell
   npm start -- serve --material=./training-material
   

3. 或启用热重载（需 Node.js 18.11+）：

   shell
   npm run dev -- serve --material=./training-material
   

测试

使用 Node.js 内置 test 模块（需 Node.js 18.3+）：

• 运行所有测试：

  shell
  npm test
  

• 运行单个测试文件：

  shell
  npm test path/to/test/file.test.js
  

源代码结构

• src/app：Web 应用源代码（嵌入训练材料）
• src/build：Web 应用构建代码（含训练材料整合）
• src/pdf：PDF 生成代码
• src/cli：命令行工具代码

代码格式化

使用 Prettier，提交前运行格式化：

shell
npm run prettier:write