zenika/sensei repository overview

⁠@zenika/sensei

The compiler for our training material. Sensei is a replacement for zenika-formation-framework⁠.

⁠Installation

⁠Using the published Docker image 🐳

• Pull the image with docker image pull zenika/sensei

• Create an alias sensei

  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'
  

  Copy

⁠Notes on running in Docker for Windows

When bind-mounting files in Docker for Windows with WSL2, the recommendation⁠ is to store files in the Linux filesystem, i.e. inside WSL2. The Linux filesystem can then be accessed from Windows through the path \\wsl$\ (or \\wsl.localhost\). When using VSCode, you can also use the WSL extension⁠ to edit files on the Linux filesystem.

Therefore it is recommended to clone the training repository in the Linux filesystem then to run the alias from WSL2.

⁠Using a Docker image built from sources 🐳

• Clone this repo and cd into the created folder
• Build the image with docker image build --tag zenika/sensei ./
• Create the same alias as for the published Docker image but without the --pull always

⁠Using Node.js

• Install with npm install --global https://github.com/Zenika/sensei

⁠Usage

⁠Help

Run sensei --help for available commands and options.

⁠Generating PDFs

• cd into a training material folder (must have Slides/slides.json and Workbook/workbook.json)
• Run sensei pdf
• PDFs are generated inside pdf folder

⁠Serving the slides and labs

• cd into a training material folder (must have Slides/slides.json and Workbook/workbook.json)
• Run sensei serve
• Navigate to http://localhost:8080/

⁠Material authoring

⁠Slides

Write slides as you would usual Reveal.js slides. Refer to Reveal's documentation⁠ for features. Note that the following plugins are enabled:

• Markdown
• Highlight
• Zoom
• Notes
• Math

⁠Workbook

Write the workbook as you would a usual markdown document.

⁠Development

⁠Running

Install dependencies (npm i) then use npm start -- to run the CLI (e.g. npm start -- serve --material=./training-material where ./training-material points to directory with training material in it). You may alternatively use npm run dev -- instead to enable restart on change (e.g. npm run dev -- serve --material=./training-material). Note that npm run dev requires Node.js 18.11 or later.

⁠Testing

Tests are written using the built-in test⁠ module, which requires Node.js 18.3 or later.

• Run all tests: npm test
• Run one test file: npm test path/to/test/file.test.js

⁠Source file structure

• src/app: source code for the web app that embeds training material
• src/build: source code that builds the previously mentioned web app, including the training material
• src/pdf: source code that builds PDFs from the training material
• src/cli: source code for the CLI

⁠Code formating

This project uses Prettier. Don't forget to format before committing! You may use npm run prettier:write to do that.