Once you create content in PreTeXt, it is time to build it, perhaps generate assets (if your project has such assets), view the result to make sure it looks good, and when you are ready, deploy your web output to a live webpage for others to marvel at.
In this chapter we will walk through the steps to do this inside a codespace environment.
Section 3.1 Build and Generate
Inside the VS Code window you opened through codespaces, have a .ptx file open. 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. To start just select “web”.
In the “Explorer” panel on the left-hand side of the window, you can expand the “PreTeXt Commands” menu and select the Build option.
You can type pretext build web from the terminal (this uses the CLI directly).
You can use the keyboard shortcut CTRL+ALT+b (or perhaps CMD instead of CTRL if you have a Mac).
If your documentment contains some more complicated elements, you might need to generate them for them to show up. The elements that require this are (depending on what your build target is):
You can generate assets in much the same way you run a build. There is a button on the top-right of the window, and option in the “PreTeXt Commands” menu, you can type pretext generate in the terminal, or use the keyboard shortcut CTRL+ALT+g.
Section 3.2 Previewing
You can check the output of what you 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 will get a choice for your viewer. We currently suggest using “Live Preview”, although on codespace this requires a few extra steps:
When the side preview opens, it will ask you if you want to open in an external browser. Click “Open in browser”.
Now close that new tab that opens, and also close the side panel in VS Code that opened.
Finally select “View” again, and it should just work. You can drag the VS Code tab to un-split the window to make it easier to view.
You can also experiment with the CLI view command, by selecting that from the pop-up menu, or by typing pretext view web in the terminal. This should pop up a new browser tab with the preview. The only reason we caution against this currently is that the local server that gets started to preview the files will keep running as long as your codespace is active, and we don't understand how this affects resource use.
When you make edits to your source files, you will need to build again, and then refresh the preview window to see the changes.
Section 3.3 Saving your work
Using codespaces will keep all your files “in the cloud” on GitHub's server. As long as you don't delete your codespace, your files will be saved there. However, you will want to push these files to your git repository on GitHub to make this save perminent. This has the benefit of allowing collaborators to access your files as well (your codespace is unique to your account).
There is a lot to learn about git, but luckily using VS Code lets you do everything you need using menus (you don't need to use the command line, unless you want to). Everything can be controlled using the Source Control view: it should be third from the top on the very left of the window, an icon with splitting paths, and likely a badge showing how many files you have changed.
Here are the basic concepts you need to understand.
The program git keeps track of all the changes you make to files inside of your repository (in this case, the folder containing your project).
-
Once you have edited your files and are happy with all of them, you tell git to track the set of changes as a commit. This creates a handy breakpoint you could return to if you want to go back to an earlier version.
There are two steps to creating a commit (which you can often do all at once in practice):
-
You stage the files you want to update in the commit.
You commit the stage files including a commit message.
Doing this in two steps can be helpful if you want to commit only some of the files that have changed.
Once you have one or more commits, you need to sync these changes with GitHub. To “upload” your changes, you push the repository. To download changes that you are someone else made, you pull the repository.
Now, how do we do these things in VS Code? Start by looking at 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 (you will see a side-by-side view of the original and updated version).
If you are comfortable staging and committing in one step, you can simply write yourself a short message in the textbox above the big green “Commit” button, and click the button. If you want to stage first, click the + next to each file under “changes” to stage them.
The green button should now turn into a “Sync” button. When you click that, it will do a quick pull and then a push, to sync changes with GitHub.
The only small point about using git is that no all files will be tracked. This is on purpose, since temporary files really should not be “remembered” using this version control setting. Which files or types of files are ignored by git is controled by the “.gitignore” file in your repository.
In particular, we do not track the output of builds. Git is used to track progress on your source, which you build into output at any time. If you want others to be able to see the output of your work without building it themselves, you need to deploy your work.
Section 3.4 Deploy
So you have worked tirelessly to prepare course notes or a book, built and previewed, synced changes using git, 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 1 . Watch the output pane for a link to your published site. (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.)
