Skip to main content
Logo image

Getting Started with PreTeXt: COMaT Workshop, May 2024

Steven Clontz, Oscar Levin

Chapter 3 Codespace Workflow

View Source
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 “PreTeXt” button in the VS Code status bar (just left of center on the bottom of the window), or use the keyboard shortcut CTRL+ALT+p, to bring up the PreTeXt Commands menu. Select “Build” from the menu. This will bring up a list of build targets. Select “web” from the list. This will build your entire project, and put the output in the build/web folder.
  • You can type pretext build web from the terminal (this uses the CLI directly). If you don’t see a terminal window at the bottom of the screen, you can open it with CTRL+`.
  • You can use the keyboard shortcut CTRL+ALT+b. This will build the project using the last build target you used. If you haven’t built yet, it will use the default build target, which is “web”.

Note 3.1.1.

All shortcuts listed in this guide assume you are using Windows or Linux. If you are using a Mac, you will need to use CMD instead of CTRL.
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):
  • <latex-image>
  • <sagemath>
  • <asymptote>
  • <youtube> (for thumbnail previews)
  • <webwork>
  • <codelense>
You can generate assets in much the same way you run a build. The PreTeXt command menu has a Generate choice that you select, and then select your target (different target formats have different requirements for what is generated). You can also type pretext generate in the terminal, or use the keyboard shortcut CTRL+ALT+g.

Note 3.1.2.

Note that generating assets requires additional software, like or Sage. Depending on your codespace setup, you can likely fix erorrs as follows.
  1. Open the file .devcontainer.json
  2. Delete the first line of the file (so that pretext doesn’t “fix” it for you).
  3. Comment out line 18 (add two forward slashes).
  4. Uncomment line 20 (remove the two forward slashes).
  5. After saving, vs-code should offer to rebuild your “container,” which you should do. Otherwise, clicking the gree button in the bottom of the window (labeled “Codespaces”) and selecting “Rebuild Container” should get you set up correctly.

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. If you use the PreTeXt Commands menu ans select “view”, you will get a choice for your viewer. We currently suggest using “Live Preview”, although on codespace this requires a few extra steps:
  1. When the side preview opens, it will ask you if you want to open in an external browser. Click “Open in browser”. If you don’t see the pop-up, you can clicke on “Port: 3000” in the bottom status bar of VS Code and select “Open in browser” from the pop-up menu.
  2. Now close the new tab that opens, and also close the side panel in VS Code that opened.
  3. 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):
    1. 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”. This will automatically take the most recent build of your web target and host it through GitHub Pages
 1 
pages.github.com/
. 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.)
PrevTopNext