Section 2.2 Example Projects
We are now ready to create our first PreTeXt project. First, let's run through the steps to start a new book, and see how to convert it to HTML and PDF. After that, we will create a very minimal article to explore the structure of a PreTeXt project.
Your First PreTeXt Book.
From a terminal, type:
pretext new book
This will create a new folder at your current location called
new-pretext-project. The folder contains the source files for your project (the files you will edit to add content to your book), as well as a folder for assets (such as external images you might put in your book), a folder for publication files (which describe some customizations for your book) and a
project.ptx file that tracks options for different output targets.
Next, change directories to the new-pretext-project. In the terminal:
Now we build a version for the web (HTML) with the following command:
pretext build web
PreTeXt can generate a wide variety of images and other assets, if you have appropriate software (such as SageMath or LaTeX) installed. To try this, in the file
source/main.ptx follow the instructions to uncomment the line
<xi:include href="./ch_generate.ptx"/>, and use the command
pretext build -g.
-g flag tells PreTeXt to generate any images described in the source and to prepare any WeBWorK exercises. After doing this once, you can omit the
-g, unless you modify the code for one of the images described in the source.
Finally, we can view the results of our conversion using this command, which starts up a simple web server so we can see all content:
pretext view web
The output from this command will give a URL to click on (and might even open your browser to that location) that should show you the web output. When you are done viewing, return to the terminal and hit
CTRL+C to terminate the server.
To build and then view something suitable for print (PDF), you would enter the following two lines:
pretext build print pretext view print
If you are building on a local machine, the view command should open your pdf viewer; on CoCalc you will get a web link for the print version. You can also directly open the file located at
A Minimal Example.
Let's back up and create a simpler project to explore. First rename the
new-pretext-project folder you just created to something like
book-example, either using your file manager or in the terminal by doing the following (assuming you were still inside that folder):
cd .. mv new-pretext-project book-example
pretext new hello
This creates another
new-pretext-project, and you can follow the directions above to navigate to it, build, and view it.
Time to look at the source. Open the file
main.ptx in the
source folder of your project. Make sure this opens in a text editor, and that you see something like this:
<?xml version="1.0" encoding="UTF-8"?> <pretext> <article> <title>Hello World!</title> <p>This is a PreTeXt document.</p> </article> </pretext>
This illustrates the structure of all PreTeXt documents. In particular, notice:
The first line says that the text file you are looking at is an XML file. This should go at the top of every pretext file, including any that you later import.
The next line and the last line of the document are the start and end of the
<pretext>tags. Every pretext document needs these to wrap all of their contents.
Inside those, we have
<article>tags, since this is an article (and not a book, which would have
Then, inside the article, we have a title (the text of the title is wrapped in the
<title>tags), followed by a paragraph (in
Notice how every opening tag (no slash) has a paired closing tag (with a slash, plus the identical name). Think of these tags as defining a box that holds either text content or other boxes (defined by a pair of opening and closing tags).
In the next section we will expand this minimal example by adding some additional content.