> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reducto.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Fonts

Fonts decide where lines break. If the layout measures text with a font that has different widths than Word's, lines break in different places and pages move. Read this page before you deploy.

## How fonts are chosen

The layout asks a **font registry** for each family name in the document (`Calibri`, `Times New Roman` …). The registry gives a face, or a fallback.

The library ships a **portable profile** in `@reductoai/portable-fonts`. It has open fonts with the same metrics as the Office fonts:

| Office font | Portable face |
| - | - |
| Calibri | Carlito |
| Cambria | Caladea |
| Arial, Helvetica | Liberation Sans |
| Times New Roman | Liberation Serif |
| Courier New | Liberation Mono |
| Georgia | Gelasio |
| Segoe UI, Segoe UI Light | Selawik, Selawik Light |
| Cambria Math | STIX Two Math (other metrics) |

Plus script fallbacks: Droid Sans Fallback for Chinese, Japanese and Korean, and a Noto face for each other script Word sets outside its Latin fonts (Arabic, Hebrew, Indic scripts, Thai, Lao, Khmer, Myanmar, Tibetan, Georgian, Armenian, Ethiopic and others). Greek and Cyrillic in a clone with no Greek or Cyrillic (Caladea, Gelasio, Selawik) take Times New Roman's or Arial's clone. These faces do not have the metrics of Word's own script fonts, so lines in those scripts can break in other places.

Selawik has no italic face, so Segoe UI italic is the upright face, slanted. A font with no clone (Aptos, Verdana, Tahoma) takes the face Word gives a missing font: Calibri's clone for most sans fonts, Cambria's for serif fonts.

The licences are in the package: `LICENSE.md`, `OFL-Gelasio.txt`, `OFL-Selawik.txt`, `OFL-Noto.txt` and `DROID-NOTICE`.

## Node

`@reductoai/docx/node` registers fonts the first time it lays out a document:

1. If `DOCX_FONT_MIRROR` is set, it uses the portable profile plus the faces in that folder. The folder must contain a `font-table.json` (see below).
2. Else, on a Mac with the Office fonts installed, it uses those fonts. This gives the closest match to Word.
3. Else (Linux servers, CI), it uses the portable profile and writes one warning:

```text theme={null}
[docx] macOS oracle fonts not found; using the bundled portable profile ...
```

The output is then deterministic on every machine.

### Use your own fonts on a server

For the document server, see [Document server fonts](https://docs.reducto.ai/office/document-server.md): it reads a folder of font files and needs no `font-table.json`.

If you have a license for the Office fonts, put them in a folder with a `font-table.json`:

```json theme={null}
{
  "families": {
    "calibri": { "regular": "calibri-r", "bold": "calibri-b", "italic": "calibri-i", "boldItalic": "calibri-bi" }
  },
  "files": {
    "calibri-r": "calibri.ttf",
    "calibri-b": "calibrib.ttf",
    "calibri-i": "calibrii.ttf",
    "calibri-bi": "calibriz.ttf"
  }
}
```

Family keys are lower case. Then start your process with `DOCX_FONT_MIRROR=/path/to/folder`.

The engine reads that folder once, when it loads. To lay out one document with other faces, give `runPipeline` or `convertDocxToPdf` a `measurer` whose `FontRegistry` has them (`registerFontFile`, `registerBuiltinFamilies`). That document then lays out with the registry's faces and nothing else. A registry that adds no faces, such as the default one or `registerPortableFonts` alone, keeps the engine's shared table at no extra cost.

`WordDocument` takes no `measurer`: register the faces on `defaultFontRegistry` (from `@reductoai/docx`) before you open the document. A document opened after that, and a `runPipeline` or `convertDocxToPdf` call without a `measurer`, lays out with them.

## Browser

A page cannot read system fonts, so you give the layout a **face provider**. It downloads only the faces that a document uses, and only once.

```ts theme={null}
import { portableFaceProvider } from "@reductoai/docx/browser";

const fonts = portableFaceProvider(
  (file) => `https://cdn.jsdelivr.net/npm/@reductoai/portable-fonts/files/${file}`,
);
```

For production, serve the files from your own origin. Copy `node_modules/@reductoai/portable-fonts/files` to your static folder and point the URL there. Or serve them from the package with a route. In Next.js:

```ts theme={null}
// app/fonts/[file]/route.ts
import { readFile } from "node:fs/promises";
import { portableFontPaths } from "@reductoai/portable-fonts";

export async function GET(
  _request: Request,
  { params }: { params: Promise<{ file: string }> },
): Promise<Response> {
  const { file } = await params;
  const path = portableFontPaths[file];
  if (!path) return new Response("not found", { status: 404 });
  return new Response(new Uint8Array(await readFile(path)), {
    headers: {
      "content-type": "font/ttf",
      "cache-control": "public, max-age=31536000, immutable",
    },
  });
}
```

Then use `portableFaceProvider((file) => `/fonts/\$\{file}`)`.

To serve other fonts, use `tableFaceProvider(table, urlFor)` with the same `font-table.json` format as `DOCX_FONT_MIRROR`.

### Why layout runs twice

A face download is async, but layout is sync. So `layoutDocxInBrowser` lays out once to find the faces the document needs, downloads them, and lays out again. When all faces are already in the cache, it lays out once. You do not need to do anything for this; it explains the first-load time.

> [!WARNING]
>
> Font files have licenses. The portable profile is open (SIL OFL and similar). Do not serve the Microsoft Office fonts from a public site unless your license permits it.
