Live editing

While the authoring workflow is already quite fast by using the publish-workshop and deploy-workshop cmdlets of the Educates CLI or update-workshop from within a running session, an even better experience would be live previews while we edit our workshop instructions.

With the Educates CLI, we can patch a deployed workshop to render local instructions instead of the ones bundled and published with the workshop. For this to work, however, we need Hugo installed locally.

Installing Hugo

Hugo is a single Go binary that can be installed via package managers for most systems.

Installing Hugo on Linux

sudo apt install hugo

sudo dnf install hugo

sudo zypper install hugo

For other distributions, please look at the installation docs.

Installing Hugo on macOS

brew install hugo

sudo port install hugo

On Windows, install Hugo inside WSL with the Linux instructions.

Patching a Workshop

Once Hugo is installed, we can patch a deployed workshop and start hosting its instructions directly from our repository. Run this from the workshop's directory:

educates serve-workshop --patch-workshop

The command patches the workshop definition in the cluster, which starts a new workshop environment whose Sessions load their instructions from a web server the command runs on your machine. Start a new Session from the training portal: as you edit the pages under workshop/content, the instructions are regenerated and the page in your browser refreshes.

When you are done, stop the command with Ctrl-C. That restores the workshop definition in the cluster, so new Sessions use the published workshop again. Then publish your changes with educates publish-workshop.

Live editing covers the instructions only. Setup scripts, exercise files and anything else in the workshop still come from what you last published: to try changes to those, publish the workshop again and start a new Session.