# Text and fonts

[Start here](https://pegmatite.dev/guide/start.md). Fetch this topic when a model carries lettering or needs a particular font.

## `text`

**Syntax:** **`text`** _text_

A line of text in the current font at the current font size. Text is a [2D shape](https://pegmatite.dev/guide/shapes.md): `extrude` raises it, and the result is an ordinary solid that is placed, anchored and signed like any other. The string may come from a variable.

```pegm
set $label "Top"
block 60 60 6
on #top x left text $label | extrude 2
```

Lettering stands out of a face as relief, as above, or is cut into it with a sign: the extrusion reaches into the material from the face.

```pegm
block 60 20 6
on #top -text "OPEN" | extrude 1
```

A string may span several lines or break them with `\n`. Each line starts below the one before, aligned on the left:

```pegm
text "OPEN
DAILY" | extrude 2
text "OPEN\nDAILY" | extrude 2
```

[Escapes](https://pegmatite.dev/guide/syntax.md) write a double quote, a backslash or a character that is hard to type:

```pegm
text "\"20\u{B0}C\"" | extrude 2   /* "20°C" */
```

Without `font`, text is drawn in a built-in sans-serif covering Latin-1 and Greek. A character the font has no glyph for is left out, with a warning.

## `font-size`

**Syntax:** **`font-size`** _size_

The height of a capital letter in mm, `10` by default, in every font: another font keeps the text the same size. Accents and tall lowercase letters may rise above it. The extrusion height is independent.

```pegm
font-size 12
text "Hello" | extrude 15
```

Like `x`, `y` and `z`, it applies to the next solid only; `!` makes it persistent and `unset` restores the default:

```pegm
!font-size 20
text "Big" | extrude 4
text "Also big" | extrude 4
font-size unset
text "Default size" | extrude 4
```

## `font`

**Syntax:** **`font`** _family_ [_weight_]

The family is a [Google Fonts](https://fonts.google.com/) name, the `https` URL of a font file, or the path of a font file on disk. It is written literally, never as a variable, because the font loads before the script runs.

```pegm
font "Isometra"
text "Hello" | extrude 2
```

The weight runs from `100`, thin, to `900`, black. A family name without one is `400`; a weight the family does not have is an error.

```pegm
font "Roboto" 700
text "Bold" | extrude 2
```

```pegm
font "https://fonts.gstatic.com/s/isometra/v3/Gg82N5ofdAjvCxbehlYclg4hLmpf.woff2"
text "From a file" | extrude 2
```

### Font files

- Formats: TrueType (`.ttf`), OpenType (`.otf`), WOFF, WOFF2; a collection (`.ttc`) gives its first font. The format is read from the content, so a URL needs no extension.
- A file holds one weight, so the weight only picks one from a variable font and is otherwise left out. A file over 10 MB is an error.
- A path ends in `.ttf`, `.otf`, `.woff`, `.woff2` or `.ttc` and is relative to the script's folder, or to the working directory for stdin. A backslash starts an escape, so write Windows paths with `/` or `\\`.
- Only the [command-line tool](https://pegmatite.dev/guide/cli.md) reads files from disk; the web app reports an error and needs a URL.

```pegm
font "fonts/Logo.otf"
text "Local" | extrude 2
```

`font` applies to the next solid only; `!` makes it persistent and `unset` returns to the built-in font:

```pegm
!font "Roboto"
text "Roboto" | extrude 2
font unset
text "Built-in" | extrude 2
```