Here we will outline the functionality of the PreTeXt-CLI. Instructions for using the CLI without any local installation can be found in Chapter 2. An easy first step toward getting PreTeXt working locally would be to download VS Code and install the pretext-tools extension (which will install the PreTeXt-CLI for you, assuming you have an appropriate version of python available).
We will work at the command-line inside of a terminal or console. If you do not know what this is, it will seem very primitive at first. This will be called a “Command Prompt” or “PowerShell” in Windows or a “Terminal” on a Mac. In Linux it may be known as a “console” or a “shell”. Whenever the guide says to enter something on the command line or in a terminal, or just to enter the command, this is what we are talking about.
Before you can install PreTeXt locally, make sure you have the following software on your computer, or else install it using instructions easily searched for online.
Python, version 3.10 or later. In a terminal, type python --version to ensure you are already set up. On MacOS or Linux, your command for python might be called python3, so also try python3 --version.
To use an HTML theme other than the default, you will need Node.js, version 18 or later. You can check if you have it installed by running node --version in your terminal.
Including the [all] at the end of the instillation command will install both optional dependencies with the CLI: pelican for generating a static landing page if you wish to deploy multiple targets, and prefigure, to include accessible prefigure graphics. You could install just one of these using pip install pretext[prefigure], for example. If something goes wrong, you can always just include the required dependencies with pip install pretext.
Newer Linux distributions and MacOS versions may give an error or warning when using pip outside of a virtual environment. It is likely best practice to use a virtual environment, especially if you use python for other projects. Some instructions are available in Section C.2.
For quick hints about what you can do, the CLI has built-in help. You can access this by entering pretext --help or pretext build --help (replacing build with new or view or generate etc.).
This documentation will assume you have version 1.0 or later of the CLI. You can upgrade the CLI to the most recent version through PIP using the command:
If you installed the PreTeXt-CLI before version 1.0, you need to manually uninstall the package pretextbook (which is what the CLI was called during early development). Run pip uninstall pretextbook and then pip install pretext te get caught up.
This creates a new book in the folder “new-pretext-project” (which you can safely rename). For a new article, use pretext new article. You might also try pretext new demo to get a project that shows off more features available, or pretext new course for a collection of course documents. pretext new slideshow will create a new project with a simple slideshow template.
A folder to place static (external) assets, such as images or data files, that you will include in your project, for example, with <image source="frog.jpg"/>.
A folder that will hold assets (such as images) generated from source, using the pretext build or pretext generate commands. You should not manually edit any contents of this folder.
A folder to hold your “publication” files used to customize how your output looks. One publication file is included, but you can have as many as you want. See Chapter 44.
An XML file called the project manifest. This specifies options for converting your source into different target outputs. We will describe the contents of this file in Subsection 5.2.7.
A simple text file that contains the version of the CLI that is initially used to build the project. If you upgrade the CLI, you will be warned to also update the version in this file once you know that things build as expected.
Once you build your project, you will get a folder called output and possibly one called .cache (which stores cached generated assets). Do not edit the contents of these folders manually; such changes will be overwritten anyway.
Additional files and folders will be generated if your project is managed by git (for example, if you use GitHub). You can expect to see a file .gitignore and folders .devcontainer and .github.
Whenever you upgrade your installation of the CLI, you should run pretext update from inside your project folder. Doing so will update any managed files that you have not edited. This can be useful to get the latest features.
Here “web” is the @name of one of the targets in the project manifest (project.ptx). To build different targets, replace it with the @name of another target, as in pretext build print.
This will direct you to open a file running in a local server (that the CLI started for you) at a provided address (perhaps http://localhost:8128/output/web). Once you have run pretext view once, you can navigate to other output targets by navigating to a different url (maybe http://localhost:8128/output/print) or just rerun the pretext view command with a different target name.
Running pretext view will attempt to open your default program for the type of file you are opening. You can prevent this attempt using the --no-launch flag.
Assuming you ran this command in a terminal, the easiest way to continue working is to open a new terminal tab to run pretext build again; the local server will continue in the original terminal until you stop it with CTRL+C.
When using pretext view, your project is only viewable on your local machine (even if you are working in a Codespace or on CoCalc). To make the output available to the public, you will need to copy the output to a web server, or use the pretext deploy command, described below.
Subsection5.2.5Hosting your project: pretext deploy
When you are ready to share your project with the world, you can copy the contents of the output/web (or whatever you called the output of your html build) to any webserver. A convenient free option is to use GitHub Pages 3
If you watch the terminal, you will either get directions for how to set up your repository, or will simply be told what the live website for your project is.
Behind the scenes, this command copies the contents of the output folders you want to deploy to a folder output/stage, and then moves the entire contents of that folder to the gh-pages branch of your github repository. If you have not already created a gh-pages branch, the CLI will create one for you. If you have not already set up your repository to track your source files, the CLI will walk you through the steps you need to get set up.
Sometimes authentication with GitHub can be tricky. Especially on Macs, it appears that conflicts can arise if you use different methods for authenticating in different applications. A fix that seems to work is to open Keychain Access, search for “github” and delete some or all of the entries you find (GitHub api seems to be a culprit). You will need to reauthenticate then, but after that, it should work.
You can deploy multiple targets, starting with the 2.0 release of the CLI. To do this, you will need to specify a @deploy-dir attribute in your project manifest for each target you want to deploy. Additionally, you should create a folder in the root of your project called site and create a landing page for your project. The site folder and the output folders for each specified project will all be copied to output/stage. We recommend using the flag --stage-only so you can preview you complete site before deploying it.
Some PreTeXt elements require special processing: WeBWorK exercises, <prefigure>, <latex-image>, <sageplot>, and <asymptote> images, as well as previews for embedded youtube videos or interactive elements. We call these elements “assets” or “generated assets”.
Prior to version 1.7 of the CLI, you would need to run pretext generate -t [target] (where “[target]” is the name of a target, like “web”) in order to generate assets. Since then, you can still do this, but it is usually not necessary: whenever you build a target, the CLI will automatically generate any assets that are out of date. If you want to force the generation of assets, you can use the -g flag when building (e.g., pretext build web -g). If you really don’t want to automatically regenerate assets, you can use the --no-generate flag when building (e.g., pretext build web --no-generate).
If you want to generate assets without building (or if you are using an older version of the CLI), the following instructions can help you limit what you generate.
You can limit which sorts of assets you generate. For example, if you edit a few <latex-image> elements, you can just generate these (for the first target in the manifest) with pretext generate latex-image. To get the same assets for a different target, use the -t flag (e.g., pretext generate -t print prefigure). If you want to generate all assets for a specific target, use the --all-assets flag (e.g., pretext generate -t web --all-assets). This will generate all assets for the specified target, regardless of whether they are out of date or not.
Valid choices for what types of assets you can generate in this specific way are: webwork, prefigure, latex-image, sageplot, asymptote, interactive, youtube, codelense, and datafile.
To be even more precise, if the element you wish to generate has an @xml:id, you can generate just that element using the -x flag. For example, if your <latex-image> has id “img-circle”, generate it with pretext generate -x img-circle
Finally, there might be times you would like to get all output formats for the assets you are generating. You can accomplish this using the --all-formats flag on pretext generate. Different output formats require different asset formats; to get just those formats for a particular target, you can use the -t flag to specify a target name.
The project manifest, always named “project.ptx”, contains information about each target you will build. Prior to version 2.0 of the CLI, it also contained the names of executables of external tools that might be needed for building targets and generating assets. (In 2.0 and later, if you need to change the default names or paths to executables, you will use a separate executables.ptx file.)
The CLI looks for this file, so you should have only one. If you have a project that was not created using pretext new, you can get a copy of the file by running pretext init. You can also get the most recent template version of the manifest by running pretext init --refresh, which will create a new versions of the files (and create a .bak backup version for those you have modified so you can compare then and update accordingly).
While we use the .ptx extension, the manifest is not technically a PreTeXt document, since it does not agree with the schema. However, it must have a specific structure to be used with the CLI. An example of a simple manifest is given in Listing 5.2.6. Note this is version 2 manifest; for a comparison of “legacy” manifests and the current format, see Appendix P.
The manifest contains a single <project> element with a @ptx-version attribute. This attribute is required and must be set to “2” for the CLI to recognize the file as a valid manifest. Additional optional attributes of <project> can also be specified, which we will describe below. The <project> element has a single child, <targets>, which contains a list of <target> elements.
Each <target> must have a @name attribute. The name (e.g., web, print) is what you specify when you run build, view, or generate for a specific target (so pretext build web, pretext view web or pretext generate -t web).
The second required attribute of <target> is @format, which must be one of html, pdf, latex, custom, epub, kindle, or braille (although the last three of these are still experimental, as of 9/1/2023).
With just these attributes, as with the manifest in Listing 5.2.6, the CLI assumes your project uses default values throughout. The following defaults are constructed from the default value for an attribute of the root <project> element with the default value for an attribute of a particular <target> element. Each of the two pieces can be overridden. The net default folders are:
In Table 5.2.7 and Table 5.2.8 we give all the attributes you can have on the <project> and <target> elements, respectively. Some attributes can be specified for both elements. In such cases, the values will be paths, and the path given in the <target>’s attribute will be relative to the path given in the <project>’s attribute. This can be useful, for example, if all targets have publication files in the same folder, but the files for some targets are different.
Optional, default: server. Valid values: server or local. Used to specify whether asymptote images should be generated using the server asymptote version or a local asymptote install.
Optional, default: the value of @name. Path to folder in which output files/folders will be created (relative to the value of @output-dir attribute of <project>).
Optional, default: generated by pretext. Only valid for formats that produce a single output file. Path to output file to be built (relative to the value of @output-dir of the same <target> element).
Optional, no default. Path to subdirectory of deployed site where this target will live. If deploying multiple targets, then this attribute must have a value for it to be deployed.
Optional, default: xelatex. Valid values: xelatex, pdflatex, or latex. Only used on targets that build with latex, to specify what latex command to call in that step.
Optional, no default. Only valid when @format is webwork or html and @platform is not runestone. Valid values: scorm or zip. Results in output being compressed (as .zip file), and if the value is scorm, the required scorm manifest is also include in the archive.
Optional, default: no. Valid values: yes or no. If yes, the target will be built as a standalone document. This will place the output adjacent to the source file, unless @output-dir is specified. Useful for creating a target for which you will specify a different source file (using the -i flag when building).
Here, the web target, with format html, will build from the root PreTeXt file "src/main.ptx", using the publication file "publication/publication.ptx", and will place the output in the folder "out/web".
The print target, with format pdf, will build from the file "src/main-print.ptx", using the publication file "publication/pub/publication.ptx", and will place the output in the folder "out/print".
In addition to the attributes available for <target> elements, there is one optional child element, <stringparams>, which can be used to specify string parameter options (see Section 28.1). These are specified using an attribute for the name of the string parameter, and the value of the attribute is the value of the string parameter. Multiple string parameters are set using multiple attributes on the single <stringparams> element. For example,
PreTeXt uses several external tools to build and generate assets. The CLI will automatically find these tools if they are installed in the default location for your operating system. If you have installed them in a non-standard location, you can specify the path to the executable in a executables.ptx file, at the root of your project. In Listing 5.2.10 we give the defaults and formatting of such a file.
Most of the time you will want to set up a project folder that will hold all the files you need for your project, including the project.ptx and publication.ptx configuration files, your possibly modular source files, and external assets. However, it is also possible to use PreTeXt to process a single file, similar to how you might with LaTeX. Starting with the CLI version 2.19.0, this can be done easily.
You can also get portable HTML output using pretext build html -i ~/Desktop/mypaper.ptx, which will create a folder mypaper_html in the ~/Desktop folder. Note that often a portable HTML build will result in a single .html file, so this can easily be shared with others or uploaded to a web server.
In addition to checking pretext --help, pretext build --help, pretext view --help, etc, you have a few options when you run into trouble. If you are getting errors that don’t make sense, even after trying follow the suggestion of the error messages, look at the time-stamped log files inside the logs folder (or the “cli.log” file if you are using a CLI version prior to 2.0), which includes debug-level log messages. You can also run the CLI using this higher level of verbosity using the -v debug option, which must go right after pretext command, before the subcommands (build, deploy, etc.). That is, enter the following for example,
