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. Note that 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.
A final note before we get started: everything we describe here can be done locally or using an online service like CoCalc 1
, which has a terminal and has all the required software (python, LaTeX, sagemath, etc) installed already. To use CoCalc, you likely will need a paid account so you have internet access (required if you want to get the most recent version of PreTeXt or want to use pretext deploy to save and host your work on GitHub).
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.8.5 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 produce a pdf, or to generate tikz images from source, you need LaTeX. Try xelatex --version to see if you already have this.
, with specific language support), but other editors such as SublimeText, atom, emacs, vi, etc. can also be used. See Appendix D.
Now we can install PreTeXt. Open a terminal and type the following:
$ pip install pretext
If this fails, try:
$ python -m pip install pretext
(or, if python3 worked above, do python3 -m pip install pretext.)
The python -m helps in case Python is on your PATH but pip is not. This is a useful fix for the rest of the commands listed for the PreTeXt-CLI.
To verify that the CLI is installed, type pretext --version (or python -m pretext --version) and you should get back a number (1.7.5, for example).
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:
$ pip install pretext --upgrade
If you want to experiment with bleeding-edge features, you can install a nightly development version of the CLI by running:
$ pip install pretext --upgrade --pre
If you ever want to downgrade to previous version, you can do that with pip as well. For example, to install version 1.7.5:
$ pip install pretext=="1.7.5"
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.
Subsection5.2.2Starting a New Project: pretext new
To generate a new book or article, from the folder in which you want to project located, type:
$ pretext new book
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.
Inside the “new-pretext-project” folder, you will find the following folders and files:
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.
A folder to hold all your PreTeXt source files. These are the main files you will edit to control the content of your project.
A file containing a list of folders and files that should not be tracked by git if you use it for version control.
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 file that you can use to describe your project.
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”. Do not edit the contents of this folder manually.
Subsection5.2.3Converting: pretext build
To convert your source into one of the available output formats, say HTML, run the command:
$ pretext build web
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.
You can also build the first (default) target of the manifest by omitting the target: just type pretext build.
Subsection5.2.4Viewing output: pretext view
After you convert your source into, say HTML, you can view the output using the command:
$ pretext view web
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 4
, and the CLI makes this especially easy.
If you already track your source files using GitHub, all you need to do is enter the following command:
$ pretext deploy
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.
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, <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 are using an older version of the CLI, or if you want to generate assets without building, 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.
Valid choices for what types of assets you can generate in this specific way are: webwork, 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
Subsection5.2.7The project manifest: project.ptx
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 time-stamped versions of the files (so your files with matching names don’t get overwritten) for you to copy from.
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.4. Note this is version 2 manifest; for a comparison of “legacy” manifests and the current format, see Appendix O.
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 he manifest in Listing 5.2.4, the CLI assumes your project uses default values throughout. In particular,
The source is source/main.ptx.
The publication if is publication/publication.ptx.
Output is stored in output/ (with each target in a subfolder identical to the target’s name).
The staging directory to preview deploys is output/stage.
Each of these can be modified by adding the appropriate attribute of either the root <project> element or a particular <target> element.
In Table 5.2.5 and Table 5.2.6 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.
All paths described below are given relative to the root of your project (i.e., the location of the project.ptx file).
Table5.2.5.Attributes available for the <project> element.
Required. Must have value 2.
Optional, default: "source". Path to folder holding main source file, relative to project root.
Optional, default: "publication". Path to folder holding publication file, relative to project root.
Optional, default: "output". Path to folder in which output files/folders for each target will be created.
Optional, default: "site". Path to folder holding user-provided landing page for deploying multiple targets.
Optional, default: "output/stage". Path to folder where deployable targets will be collected before they are deployed.
Optional, default: "xsl". Path to folder holding custom xsl files.
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.
Table5.2.6.Attributes available for the <target> elements.
Required. The name you use when executing a CLI command.
Required. Valid values: "html", "pdf", "latex", "epub", "kindle", "braille", "webwork", and "custom". The format the target will be built into.
Optional, default: "main.ptx". Path to the root source file of the project (relative to the value of the @source of <project>).
Optional, default: "publication.ptx". Path to publication file (relative to the value of @publication attribute of <project>).
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, default: None. 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: None. Path to custom XSL file (relative to the value of @xsl attribute of <project>). Required when @format is "custom".
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, default: "emboss". Valid values: "emboss" or "electronic". Only used when @format is "braille", to specify the mode for braille.
Optional, default: None. Valid values: "runestone". Only valid when @format is "html". Used to specify that the target will be hosted on Runestone.
Optional, default: None. Valid values: "zip". Only valid when @format is "html" (but @platform is not "runestone") or "webwork". Results in output being compressed (as .zip file).
Optional, default: "server". Valid values: "server" or "local". Overrides the @asy-method attribute on <project>.
Example5.2.7.Example Project Manifest.
To illustrate how the relative paths work, with attributes on both <project> and <targets> elements, consider the following manifest:
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.
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.8 we give the defaults and formatting of such a file.
Prior to version 2 of the CLI, these executables were contained in the project.ptx file. If you are using a version prior to 2.0, see Appendix O.
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,