Skip to main content

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 publisher 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:

cd new-pretext-project

Now we build an HTML version with the following command:

pretext build html -d

The -d flag tells PreTeXt to generate any images described in the source. After doing this once, you can omit the -d, 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:

pretext view html

The output from this command will give a url to click on that should show you to html output.

To build and then view a PDF, you would enter the following two lines:

pretext build pdf
pretext view pdf

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

Now enter:

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 <book> tags instead).

  • Then, inside the article, we have a title (the text of the title is wrapped in the <title> tags), followed by a paragraph (in <p> tags).

  • 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.