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 theBuild ...
option and chooseweb
. - 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.
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/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.
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
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 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.

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.)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
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.)groups.google.com/g/pretext-support
pages.github.com/