Skip to main content

The PreTeXt Guide

Section 2.2 Your First PreTeXt Document

Subsection 2.2.1 Building for web

Inside the VS Code window you opened through Codespaces, open main.ptx. You can build your entire project in a few different ways.
  • Click the green triangle in the top-right corner of the window (hovering will show Build (select target)). A window will pop up asking for a target to build: choose “web”.
  • In the “Explorer” panel on the left-hand side of the window, you can expand the “PreTeXt Commands” menu and select the Build default target option, or the Build ... option and choose web.
  • You can use the keyboard shortcut CTRL+ALT+b (replacing CTRL with CMD if you have a Mac).
The resulting HTML files will be available in the output/web directory of your project.
Screenshot of VS Code PreTeXt palette in Codespaces
Figure 2.2.1. PreTeXt commands in Codespaces

Subsection 2.2.2 Viewing

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.

Subsection 2.2.3 Building \(\LaTeX\) and PDF

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/
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.

Subsection 2.2.4 Saving your work

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 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 1  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.
Screenshot of VS Code sidebar in Codespaces
Figure 2.2.2. Filenames changing color as they are edited in Codespaces
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.
Screenshot of VS Code Git diff in Codespaces
Figure 2.2.3. A “Git diff” showing changes in a file
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”.
Screenshot of VS Code source control in Codespaces
Figure 2.2.4. Commiting and syncing changes
To see that this is successful, return to (your Codespace lives at, 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.)

Subsection 2.2.5 Generating assets

If your document contains certain elements, you might need to generate their assets for use in certain output formats. Depending on your build target, these include:
  • <latex-image>
  • <sagemath>
  • <asymptote>
  • <youtube>
  • <webwork>
  • <codelens>
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.

Subsection 2.2.6 Deploy

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 2 . Watch the output pane for a link to your published site; unlike the preview link you've been using on that's private to only you, this 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.)