Skip to main content

The PreTeXt Guide

Robert A. Beezer, David Farmer, Alex Jordan, Mitchel T. Keller, Oscar Levin

Section 2.3 Installing PreTeXt

The browser-based GitHub Codespaces workflow described in Section 2.1 is a quick and easy way to use PreTeXt without needing to install any additional software. If you prefer to have a local setup of PreTeXt, we recommend one of the following three setups.
🔗

Subsection 2.3.1 Option 1: Installing a Docker container

The closest thing we have to a single click installer is to use a Docker container that includes all the software needed to run PreTeXt. In fact, the setup described in this section results in an identical environment to the one used in GitHub Codespaces, but it is all locally running on your own computer. The directions for all operating systems are the same (since the two programs you need to download and install are available for Windows, Mac, and Linux).
🔗
The one downside to this approach is that you will need a fair amount of disk space (around 5 GB all together), and some of that space will be used to install tools like and SageMath that you might already have installed anyway.
🔗
Here are the steps required to use this option.
  1. Download and install Visual Studio Code
     1 
    code.visualstudio.com/
    . This is the desktop version of the text editor used in Codespaces (and is great for all your text editing needs, not just PreTeXt).
    🔗
    🔗
  2. Download and install Docker Desktop
     2 
    www.docker.com/products/docker-desktop
    . Once installed, start Docker Desktop and agree to the licensing terms. You should not need to create an account.
    🔗
    🔗
  3. Download the PreTeXt Codespace
     3 
    github.com/PreTeXtBook/pretext-codespace/archive/refs/heads/main.zip
    zip file and extract it to a location of your choice.
    🔗
    🔗
  4. Launch Visual Studio Code. Use the “File” menu to select “Open Folder...” and navigate to the folder where you extracted the zip file in the previous step. Select that folder and click “Open”.
    🔗
    🔗
  5. You will likely get a popup in the lower right corner of the window asking if you want to install the devcontainer extension, or if you want to open the current workspace in a devcontainer. You do want to do both of these. If you don’t get this message, you can install the “Dev Containers” extension from the Extensions view (click the square icon on the left sidebar) and then use the Command Palette (CTRL+SHIFT+P) to run the command “Dev Containers: Reopen in Container”.
    🔗
    🔗
The last step will take a few minutes the first time since it must download the container image.
🔗
Upon completing the steps above, you can create a new project and build/view/deploy just like described in Section 2.2.
🔗
Whenever you work on a project locally, you will want to open it in the container (but next time it will boot up much faster since you will already have the container image downloaded).
🔗
🔗

Subsection 2.3.2 Option 2: Installing the PreTeXt CLI and Additional Software

The PreTeXt CLI is a Python package that can be installed on your computer. This option is more lightweight than using a Docker container, but it does require you to install several prerequisite programs (including Python itself).
🔗
Detailed instructions for installing the PreTeXt CLI with PIP are available in Section 5.2. If you know what you are doing, you can just run `pip install pretext[all]` to get all the python and core parts of PreTeXt.
🔗
This option is great if you already have a lot of the software that would be duplicated in the docker image from Option 1. In the following list, only python is strictly required, but many features of PreTeXt will not work without the other software.
  • Python (version 3.10 or later); required.
    🔗
    🔗
  • Node.js (version 18 or later); required to build custom themes for HTML and to build Braille and some epub targets.
    🔗
    🔗
  • Git; required to store your project on GitHub and use the `pretext deploy` command to host your project on GitHub Pages.
    🔗
    🔗
  • PreFigure; required to build <prefigure> images. You can get this as part of the PreTeXt CLI installation, if you install the cli with pip install pretext[prefigure], although you might need some additional system libraries installed. See PreFigure’s website
     4 
    prefigure.org/
    for more information.
    🔗
    🔗
  • (any standard distribution, including TeXLive, MiKTeX or TinyTex will work); required to build PDF output and if your document includes TiKz images (in a <latex-image> element).
    🔗
    🔗
  • SageMath (version 10.0 or later recommended); required to build SageMath output and if your document includes sageplots (in a <sageplot> element).
    🔗
    🔗
🔗
While you can use any text editor you like for authoring PreTeXt documents, Visual Studio Code is highly recommended due to the availability of the pretext-tools extension which provides syntax highlighting, autocompletion, and other features that make authoring PreTeXt documents much easier. You can install this extension from the Extensions view in Visual Studio Code (click the square icon on the left sidebar) or by searching for pretext-tools in the Extensions Marketplace (it is automatically installed if you use the Docker container from Option 1).
🔗
🔗

Subsection 2.3.3 Option 3: Running PreTeXt “from source”

For advanced users, especially if you want to contribute to the development of PreTeXt, you can run PreTeXt without the CLI. To do this, you will need to clone the PreTeXt repository
 5 
github.com/PreTeXtBook/pretext
and install the required dependencies manually. This is required if you want to run the PreTeXt script 47 or even just use xsltproc 46 to process your PreTeXt documents. Additional information is available in the linked sections.
🔗
Some context for experienced Python developers: PreTeXt is an open-source XML
 6 
en.wikipedia.org/wiki/XML
language primarily powered by XSLT
 7 
en.wikipedia.org/wiki/XSLT
and Python
 8 
en.wikipedia.org/wiki/Python_(programming_language)
tools. PreTeXt development is primarily split over two GitHub repositories: PreTeXtBook/pretext
 9 
github.com/PreTeXtBook/pretext
for the “core” functionality of PreTeXt, and the more recent PreTeXtBook/pretext-cli
 10 
github.com/PreTeXtBook/pretext-cli
that packages up these resources into a Python package with several UX enhancements such as a simplified command line interface and project management that does not require the use of custom makefiles. Instructions for developing with the CLI are available in its repository’s README file.
🔗
If you’re interested in potentially contributing back to PreTeXt someday, please feel free to request to join our developer Google Group
 11 
groups.google.com/g/pretext-dev
and say hello!
🔗
🔗
🔗
PrevTopNext