The PreTeXt Guide

You can preview these HTML files you just built using the View command. Again, you can access this in multiple ways: top-right icon or PreTeXt Commands menu. When you use either of these, you may be given options on how to view the document, depending on what VS Code plugins you have available to you. Try one or another until you're able to view your web build in either a new tab of your browser or a tab within VS Code.

Now is a great time to try to make edits to your source files (maybe change the title). Note that these changes aren't updated live in your preview: you will need to build again, and then refresh the preview window to see them.

The instructions above can be repeated to produce \(\LaTeX\) code: just choose print-latex instead of web as your target. The resulting files are available in output/print-latex.

Of course, it'd be even more convenient to produce a PDF directly. This requires software that can process \(\LaTeX\text{,}\) which is not installed in the PreTeXt Codespace by default. This can be accomplished by copy-pasting the following line into a “terminal” and pressing Enter to run the command. (Use Ctrl+` to make a terminal appear below the text editor if it's not already on screen.)

sudo bash ./.devcontainer/postCreateCommand.sh

After everything is installed, repeat the above instructions with the print target to produce a PDF. It can be downloaded by right-clicking output/print/main.pdf in the VS Code file explorer, or previewed using a View command.

Alternatively, the next time you create a Codespace, you can click the three dots next to the + and select the “devcontainer” that has “pretext-full” in its name.

In any case, once you install this software once, you should be good to go as long as your Codespace exists.

Using Codespaces will keep all your files “in the cloud” on GitHub's server, saved automatically as you edit. As long as your Codespace is active, your files will be saved there for your private use.

However, you will want to periodically commit & sync these files to your git repository on GitHub (located on the web somewhere like https://github.com/user-name/repository-name). This creates a backup of your work, and has the added benefit of allowing collaborators (not to mention members of the PreTeXt community who watch the PreTeXt-support¹ Google group) to access your files as well.

While Git and GitHub have a lot of features, fortunately there's a very simple way to use them via Codespaces. As you edit files, you'll notice that their filenames will turn orange, and new files will appear green. Likewise, a blue number will appear in the left sidebar.

This blue badge is next to the Source Control view. You will notice a list of files that were changed; you can click on any of these to see what the changes are.

Type a message describing the changes you've made then click the green “Commit and Sync” button. If it just says “Commit”, use the drop-down menu to choose “Commit and Sync”.

To see that this is successful, return to https://github.com (your Codespace lives at github.dev), then find your public repository page where you first created the Codespace. You should see your files with all your committed/synced changes. (That is, most of them: many files, such as log files and temporary build files, are not tracked by Git. This is no problem: they are created during a build automatically and don't need to be saved or shared with others.)

You can generate assets in much the same way you run a build, though you may need to first install the extra software as described in Subsection 2.2.3. After that is done, you can use the button on the top-right of the window, the option in the “PreTeXt Commands” menu, or the keyboard shortcut CTRL+ALT+g.

So you have worked tirelessly to prepare course notes or a book, built and previewed, synced changes to your git repository, and now you are ready to share the results of your efforts with the world. It's time to deploy your project!

With our Codespace setup this is simple. From the “PreTeXt Commands” menu, click on “Deploy to GitHub”. This will automatically take the most recent build of your web target and host it through GitHub Pages². Watch the output pane for a link to your published site; unlike the preview link you've been using on github.dev that's private to only you, this github.io link is ready to share with the world. (It can take a few minutes for the site to get set up or updated; there should be another link to view the progress of the GitHub “action” that reports the progress.)