Skip to main content

Getting Started with PreTeXt

Geoff Cox, Ph.D.

Section Part 6. Build and Preview

Building a PreTeXt project means running the toolchain that converts your source XML into polished HTML (or PDF, or ePub). You’ll do this dozens of times as you write, so it’s worth learning two ways to trigger it: a button and a command.
🔗

Build the HTML version.

  1. Look at the blue bar at the very bottom of the Codespace window. Find the ▷ PreTeXt button.
    🔗
    The PreTeXt button on the bottom status bar, shown as an arrow followed by the word "PreTeXt".
    🔗
  2. Click it. A small menu appears. Choose Build default target.
    🔗
    🔗
  3. A terminal panel opens and shows the build’s progress. The first build takes a little longer than subsequent ones because it downloads some supporting files. Typical time: 30 to 60 seconds.
    🔗
    🔗
  4. When you see a success message at the end of the terminal output, expand the output folder in the file explorer. You should see a web subfolder containing an index.html.
    🔗
    🔗
🔗
🔗

Preview the HTML version.

Don’t try to open index.html by hand, it won’t render correctly from the file system. Use the built-in preview instead.
🔗
  1. Click ▷ PreTeXt on the blue bar again.
    🔗
    🔗
  2. Choose View Full Document, then web.
    🔗
    🔗
  3. A new tab opens with your document rendered as a real web page: table of contents on the left, your lesson in the middle, equations typeset with MathJax.
    🔗
    🔗
🔗
🔗

Build a PDF too.

  1. Click ▷ PreTeXt one more time and choose Build Another Target.
    🔗
    🔗
  2. From the list, pick print. This triggers a -based build to produce a typeset PDF, which lands in output/print/.
    🔗
    🔗
  3. The first PDF build takes longer because it needs to fetch packages. Expect two or three minutes.
    🔗
    🔗
  4. When it finishes, preview it the same way as the HTML: ▷ PreTeXt → View Full Document → print.
    🔗
    🔗
🔗
🔗

The rebuild rhythm.

The preview does not update on its own. Every time you edit the source, you need to build again and then refresh the preview tab. You’ll internalize this rhythm in the first ten minutes: edit, build, refresh, look.
🔗
🔗

✓ You know it worked when….

  • The output folder exists and has a web/index.html inside it.
    🔗
    🔗
  • A browser tab is showing your lesson with a navigation sidebar.
    🔗
    🔗
  • Optionally, you also have a output/print/main.pdf.
    🔗
    🔗
🔗
🔗

If you get stuck: build fails with a red error.

Almost always a missing or mismatched tag in the source. Read the error message, which will usually include a line number. Double-check that every <tag> you added has a matching </tag>. If you can’t find it, copy the starter block from Part 5 again carefully. Don’t panic at red text. These errors are routine and fixable.
🔗
🔗

If you get stuck: preview is blank or stale.

Build again first, then refresh the preview tab with F5. If that doesn’t help, close the preview tab and reopen it with ▷ PreTeXt → View Full Document → web.
🔗
🔗
🔗
PrevTopNext