Getting Started: Use a Unicode Font

You’ve created your first Tectonic document. Great! Now, let’s start exploring the ways in which Tectonic helps you create modern technical documents.

We’ve already seen a few ways that Tectonic differs from traditional TeX engines. Perhaps the most fundamentally important difference, however, is the one that we’ll explore in this section.

Note: This Getting Started guide uses what we call the “V2” interface to the Tectonic command-line tool. The V2 interface coexists with, but has a fairly different approach than, the “V1”interface. We are gradually migrating from V1 to V2. Neither interface (V1 or V2) is the same as the one exposed by classic TeX tools such as pdflatex.


When TeX was first developed more than 40 years ago, digital systems for representing human writing were pretty primitive. Because TeX needed to represent a variety of languages and mathematics, it was endowed with comparatively sophisticated tools to both accept and emit characters that aren’t found in standard English. TeX’s good multi-lingual support was one of the things that made it groundbreaking. Eventually, however, a consortium of major technology companies developed the much more comprehensive Unicode standards for representing the world’s writing systems digitally. By now, they’re universally adopted. So while the TeX ecosystem started out ahead of the curve, some of its core systems are designed around an incompatible and, frankly, dead-end framework.

That is not to imply that the whole TeX universe is stuck in the past! Many people have worked extremely hard to bridge the worlds of TeX and Unicode. The code in Tectonic, in particular, is based on XeTeX, which adds Unicode support to the classic TeX experience. Without the efforts of the XeTeX team and many other dedicated volunteers in the TeX world, Tectonic wouldn’t be able to offer Unicode support.

Modern Fonts

Tectonic’s support for Unicode allows it to take advantage of modern fonts that are distributed using formats such as OpenType. Besides opening up access to a whole world of typographic progress — a good font is the result of years of expert effort — this support positions Tectonic to create outputs in not just PDF but HTML formats. HTML capability is still under development, but it’s one of the prime reasons that the Tectonic project was started.

The choice of fonts is foundational to TeX’s document processing, so modern fonts aren’t automatically activated. To start using a nice new font like TeX Gyre Pagella (derived from Palatino), open up your src/_preamble.tex file and add the following lines after the \documentclass command:

  Extension = .otf,
  UprightFont = *-regular,
  BoldFont = *-bold,
  ItalicFont = *-italic,
  BoldItalicFont = *-bolditalic,

Now rebuild your document:

$ tectonic -X build

You’ll probably see Tectonic download some files: namely, the new font files that you have started using. Tectonic’s ability to fetch such files on the fly is why its installation is so much easier than a traditional TeX engine.

If you open up your rebuilt document, it will be using your new font, although the difference can be difficult to detect with such a small amount of sample text.

Unicode Input Text

Tectonic’s support for Unicode broadens its output capabilities through the use of modern fonts. But that’s not all: Unicode also broadens the inputs that Tectonic accepts.

With Tectonic, you can type non-English characters directly into your input TeX files, which are parsed assuming the virtually-universal UTF-8 Unicode text encoding. For instance, you can open up your src/index.tex file and copy-paste in the following verse with accented characters:

Ô que ma quille éclate! Ô que j’aille à la mer!

Rebuild your document and see your new text in the output:

$ tectonic -X build

Whatever, you might say. I know how to get these accented characters with TeX commands:

\^O que ma quille \'eclate! \^O que j'aille \`a la mer!

Fair enough. But now try typing in Bashô’s “old pond” haiku:


We’ll wait.

(Note, however, that if you copy-paste this text into our sample document, it won’t work: you haven’t activated a font able to handle the Japanese characters. You’ll get a lot of warnings to that effect.)