All Ximera files must be hosted in a git repository. As an author, you have some choices as to how you proceed.

Starting fresh is easy. Select one of following repositories as a template:

• https://github/ximeraProject/ximeraFirstSteps for playing around with some examples.
• https://github/ximeraProject/ximeraNewProject for a minimal structure to get started.

When you are logged in to GitHub, you will in both cases have the option to make a new repository using the green “Use this template” button. Once the template is made, you are ready to go!

To deploy an existing repository from a codespace copy the following files from either ximeraFirstSteps or ximeraNewProject into your repository.

.devcontainer/

(folder needed to be able to start a GitHub codespace)

xmScripts/

folder with the Ximera build and deploy script and config.

.vscode/

folder with VS Code settings, e.g. the buttons for Ximera compilation.

.xmKeyFile

a ‘dummy’ gpg-key file needed to preview your work in a Codespace.

.gitignore

replace yours or merge them if you alrady have one.

Commit your changes to GitHub and check online that the files were added. Start a Codespace in your repository to build, edit and preview your course.

Deploying an existing repository without Codespaces, but working on your machine is more involved, and requires

Docker:

a development utility to easily run self-contained applications on your computer. Install and start Docker, it runs in the background and will start the Ximera container that contains TeX.

VS Code Desktop:

a popular text-editor with strong LaTeX, git, and Docker integration. It enables a UNIX-like command line interface on Windows machines via Microsoft’s WSL (Windows Subsystem for Linux).

Contact the Ximera developers for assistance. A typical workflow is:

(a)

Open Docker and minimize the window.

(b)

Open VS Code, do File \(\to \) Open Folder, and select the folder of your git repo.

(c)

To open files, do Ctrl-p and start typing file names. Any file committed to your git repository will be found, and files in .gitignore, will not be shown.

(d)

To run a special command (like search and replace) do Ctrl-Shift-p, and search for the command.

(e)

To toggle a UNIX-like terminal, use Ctrl-~. Note, technically it is Ctrl-‘, but perhaps this is more confusing than our misdirection.

Now, copy the same files as above from either ximeraFirstSteps or ximeraNewProject into the repository you wish to deploy.

.devcontainer/

(optional: provides a Codespace setup)

xmScripts/

(build scripts and config)

.vscode/

(optional, but strongly advised)

.gitignore

(optional, but strongly advised)

Commit your changes to GitHub and view your repository online via a web browser to ensure that the files were added.

Now, move the .xmKeyFile to your repository. If deploying on your machine, you do not need to commit the .xmKeyFile to the repository. But surely never commit a non-dummy key!