# Проекты Typst

Закрепляйте версию Typst для каждого проекта, добавляйте пакеты из Typst Universe, управляйте шрифтами, вариантами сборки и воспроизводимыми PDF и конвертируйте проект LaTeX в Typst.

В комплект Oleafly входят Typst 0.15.1 и языковой сервер Tinymist 0.15.8, поэтому новый проект Typst компилируется без единой установки. Эта страница описывает, что можно менять: какой Typst использует проект, откуда берутся его пакеты и шрифты и как один исходник собирает больше одного PDF. О синтаксисе и панели инструментов начинайте со статьи [Писать в Typst](/docs/writing/typst/).

## Версии Typst

Откройте **Настройки → Движки → Typst**. Первая карточка — **Typst (встроенный)**, версия, которая поставляется с приложением. Если `typst` уже установлен на вашем компьютере, находится в вашем `PATH`, в папке Homebrew или в `~/.cargo/bin`, вторая карточка показывает его как **Typst на этом компьютере**. Проекты, закрепляющие именно эту версию, могут компилироваться с ней.

Ниже находится список **Версии** с Typst от 0.11 до 0.15, от новых к старым. Каждая строка показывает дату выпуска, размер загрузки, откуда взята копия (**Встроенная**, **Скачанная** или **Системная**) и, после установки, выпуск Tinymist, который она использует.

- **Установить** скачивает эту версию. Oleafly сначала пробует собственное зеркало, а затем GitHub и проверяет архив и программу внутри него по контрольным суммам SHA-256, встроенным в приложение. Файл, который не совпадает, отбрасывается, а неудавшаяся или отменённая установка не оставляет после себя ничего. Загрузки живут в `~/.oleafly/toolchains/typst/`.
- Круглая кнопка слева от установленной строки делает эту версию версией по умолчанию.
- **Удалить** удаляет скачанную версию. Версию по умолчанию удалить нельзя, поэтому сначала выберите другую версию по умолчанию.

### Версия по умолчанию и закрепление в проектах

Новые проекты Typst закрепляют версию по умолчанию. То же делают проекты, созданные из шаблона, импортированные проекты и связанные папки. Закрепление хранится в `project.json` проекта как номер версии, а не путь, поэтому оно продолжает работать после того, как вы переместили проект или открыли его на другом компьютере.

Изменение версии по умолчанию позже не затрагивает существующие проекты. Это сделано намеренно: закреплённая статья сохраняет те же переносы строк и число страниц, когда Oleafly переходит на более новый Typst.

Чтобы сменить версию одного проекта, откройте стрелку рядом с **Скомпилировать заново** и посмотрите раздел **Версия Typst (этот проект)**. **По умолчанию** следует версии, выбранной в настройках, и снимает закрепление. Остальные пункты — версии, установленные на этом компьютере, с пометками **[встроенная]** или **[системная]** там, где это применимо. Чтобы использовать версию, которой нет в списке, сначала установите её в настройках.

### Когда закреплённая версия отсутствует

Если вы открываете проект, закрепляющий версию, которой на этом компьютере нет, Oleafly не станет тихо собирать его другим Typst. Компиляция останавливается с сообщением «Typst 0.13.1 не установлен», и предпросмотр предлагает две кнопки:

- **Скачать Typst 0.13.1** устанавливает закреплённую версию и компилирует снова. Она появляется, когда эту версию предлагает Oleafly.
- **Использовать Typst 0.15.1**, названная в честь вашей версии по умолчанию, снимает закрепление и компилирует снова с версией по умолчанию.

Меню компиляции помечает закрепление **[не установлена]**, пока вы не выберете одну из них.

### Попробуйте более новую версию перед переходом

С открытым проектом Typst вкладка Typst в настройках показывает **Попробовать более новую версию**, когда установлен более новый Typst. Выберите **Проверить с Typst 0.15.1** (или ту версию, которая там названа). Oleafly собирает проект дважды во временных папках: один раз с текущей версией проекта и один раз с более новой. В вашем проекте ничего не меняется.

Отчёт показывает, удалась ли каждая сборка, её число страниц, её ошибки и предупреждения. Он сообщает, меняется ли число страниц. **Новое в Typst 0.15.1** перечисляет сообщения, которые выводит только более новая версия, а **Больше не выводится в Typst 0.15.1** — те, что исчезают. Щёлкните сообщение, чтобы открыть его файл на этой строке.

Если вам нравится увиденное, **Перейти на Typst 0.15.1** закрепляет проект за более новой версией. **Проверить снова** повторяет обе сборки после того, как вы что-то исправили.

### Языковой сервер следует за версией

Tinymist обеспечивает автодополнение, справку при наведении, переименование и форматирование в файлах Typst (см. [Анализ кода](/docs/code-intelligence/#typst-files)). У каждой минорной версии Typst свой выпуск Tinymist, и проект общается с тем, который соответствует его версии Typst.

Встроенный Tinymist покрывает Typst 0.15. Когда вы открываете проект, закреплённый за более старой линией, Oleafly скачивает соответствующий Tinymist в фоне, с той же проверкой контрольных сумм, и статус гласит: «Скачиваем Tinymist 0.13.30 под версию Typst этого проекта.» Если загрузка не удалась, Oleafly попробует ещё раз позже. Когда настройки находят загрузки Tinymist, которые больше не нужны ни одному установленному Typst, предлагается **Удалить неиспользуемые скачанные языковые серверы**.

### Что умеет каждая версия

Старые версии существуют, чтобы проекты, начатые на них, продолжали собираться так же. Некоторые возможности зависят от того, что поддерживает сама версия Typst:

| Возможность | 0.11 | 0.12 | 0.13 | 0.14 и новее |
| --- | --- | --- | --- | --- |
| Только шрифты проекта | Нет | Да | Да | Да |
| Воспроизводимая сборка | Нет | Да | Да | Да |
| Диапазоны страниц в экспорте PNG и SVG | Нет | Да | Да | Да |
| PDF/A | Нет | PDF/A-2b | PDF/A-2b, PDF/A-3b | Все уровни PDF/A, которые предлагает Typst |
| PDF/UA-1 | Нет | Нет | Нет | Да |
| Пакеты в папке проекта | Нет | Да | Да | Да |
| Экспорт HTML, а также экспорт Word или Markdown через HTML-вывод Typst | Нет | Нет | Да | Да |
| [Синхронизация исходника и PDF](/docs/synctex/) | Нет | Нет | Да | Да |
| Тегированный PDF при каждой компиляции | Нет | Нет | Нет | Да |

Список шрифтов в Typst 0.15 и новее может сообщать, откуда берётся каждый шрифт. Когда настройка не может примениться к версии, которую использует проект, меню компиляции помечает её **Нужен более новый Typst**.

## Пакеты из Typst Universe

Выберите **Пакеты Typst** — значок пакета в правом конце панели инструментов Typst. Ищите в Typst Universe по названию, ключевому слову или категории. У каждого пакета показана его последняя версия, а пакет, которому нужен более новый Typst, чем использует проект, сообщает об этом: «Нужен Typst 0.14.0. Этот проект использует Typst 0.13.1.»

**Вставить импорт** пишет строку `#import` в начало открытого файла Typst. **Копировать импорт** вместо этого помещает её в буфер обмена.

Typst скачивает пакет `@preview` при первой компиляции, импортирующей его, и хранит его в кэше, общем для всех проектов. Список пакетов тоже кэшируется. Офлайн диалог показывает последний полученный список с его датой.

### Более новые выпуски

Когда импорт называет выпуск более старый, чем тот, что на Typst Universe, номер версии подчёркивается с подсказкой вроде «Доступен cetz 0.4.2. Этот импорт использует 0.3.4.» Карточка подсказки предлагает **Обновить до 0.4.2**, что меняет номер версии в импорте. Прочитайте список изменений пакета, прежде чем принять его, потому что новый выпуск может изменить обращение к пакету. Наведение на импорт также предлагает **Открыть в Typst Universe**.

### Держите пакеты внутри проекта

В разделе **Пакеты проекта** того же диалога **Скопировать пакеты в проект** копирует каждый пакет, который импортирует проект, в папку `typst-packages` в корне проекта. Он также копирует пакеты, которые импортируют те пакеты, и включает **Использовать пакеты из папки проекта**.

С этого момента Typst ищет сначала в `typst-packages`. Проект со скопированными пакетами компилируется офлайн и на любом компьютере, и папку можно положить в Git вместе с исходником. Пакет, который вы не скопировали, по-прежнему берётся из общего кэша. Для этого нужен Typst 0.12 или новее, а в проекте, закреплённом за 0.11, диалог просит сначала сменить версию.

Если пакета ещё нет в кэше, диалог называет его: «Этих пакетов нет в кэше пакетов: …». Скомпилируйте один раз при подключении к сети, затем скопируйте пакеты снова.

### Офлайн-режим

С включённым **Офлайн-режимом** в **Настройки → Общие** Typst не может ничего скачивать. Каждый пакет уже должен находиться в общем кэше или в `typst-packages`. Если его там нет, компиляция завершается ошибкой, и сообщение называет пакет, так что вы знаете, что получить при следующем выходе в сеть.

## Шрифты

Typst ищет шрифты в четырёх местах: шрифты, встроенные в Typst, шрифты, установленные на вашем компьютере, наборы шрифтов, которые вы скачиваете в Oleafly, и папки шрифтов внутри проекта. Положите файлы шрифтов в папку с именем `fonts` в корне проекта, и их подхватят и компилятор, и языковой сервер. Дополнительные папки можно перечислить в `typst.font_paths` в `project.json`. Папки вне проекта игнорируются.

Под **Шрифты (этот проект)** в меню компиляции по умолчанию включено **Использовать системные шрифты**. **Только шрифты проекта** запрещает Typst читать шрифты, установленные на этом компьютере. PDF тогда получается одинаковым на любой машине, а если документ просит шрифт, которого в проекте нет, вы узнаете об этом на своём компьютере, а не на компьютере соавтора.

Чтобы выбрать основной шрифт, откройте **Настройки документа** — значок ползунков на панели инструментов Typst — и щёлкните **Шрифт текста**. Список показывает каждое семейство, которое Typst может найти с текущими настройками шрифтов проекта. В Typst 0.15 и новее каждое семейство несёт метку **Проект**, **Система**, **Набор шрифтов** или **Встроенный**. Выберите одно и нажмите **Применить**, и Oleafly впишет его в правила `#set` документа.

### Наборы шрифтов

В **Настройки → Загрузки → Шрифты** есть пять бесплатных наборов шрифтов для Typst: **Китайский, японский и корейский**, **Классические текстовые**, **Современные без засечек и с засечками**, **Код** и **Значки и эмодзи**. После загрузки набора каждый проект Typst может использовать его шрифты по имени, и то же верно для загрузок Lato, PT Sans и PT Serif на этой вкладке. Набор подключается к компиляциям только после того, как загрузка завершена целиком, поэтому недокачанный набор никогда не влияет на сборку.

Проекты с режимом **Только шрифты проекта** или **Воспроизводимая сборка** наборы шрифтов не читают. Для них скопируйте файл шрифта в папку `fonts` проекта.

### Символы, которые выглядят как квадратики

После каждой компиляции Oleafly проверяет, есть ли символы, которые не смог нарисовать ни один доступный шрифт. Typst рисует такие символы квадратиками. Если они найдены, компиляция получает предупреждение, а над редактором появляется уведомление:

- **Пустые квадратики** означают, что ни в одном шрифте, доступном Typst, этих символов нет, и предупреждение называет несколько из них. Если их покрывает набор шрифтов, как набор «Китайский, японский и корейский» покрывает текст CJK, а набор «Значки и эмодзи» — эмодзи, уведомление предлагает **Скачать шрифты** с размером загрузки, а журнал предлагает **Скачать и скомпилировать**. В остальных случаях добавьте шрифт с этими символами в папку `fonts` проекта.
- **Квадратики со знаком вопроса** означают, что Typst нарисовал символы шрифтом-заменителем. Укажите шрифт с этими символами в поле **Шрифт текста** в **Настройках документа** или в списке шрифтов, например `#set text(font: ("Libertinus Serif", "Apple SD Gothic Neo"))`.
- В проекте с режимом **Только шрифты проекта** наборы шрифтов и системные шрифты не действуют. Добавьте шрифт в папку `fonts` или переключите проект на **Использовать системные шрифты** и **Стандартная сборка**.

**Настройки документа** в уведомлении открывают панель, где выбирается основной шрифт. Закройте уведомление, чтобы скрыть его для этого предупреждения.

## Варианты сборки и sys.inputs

Вариант сборки — это именованный набор значений, который документ читает через `sys.inputs`. Используйте варианты, когда один исходник должен давать разные PDF: например, анонимную версию для рецензирования и финальную версию для публикации или черновик с водяным знаком.

Документ решает, что делает каждое значение. Значения всегда приходят как текст:

```typst
#let draft = sys.inputs.at("draft", default: "false") == "true"

#if draft [*Draft. Do not circulate.*]
```

Чтобы настроить вариант:

1. Откройте **Настройки документа** и прокрутите до **Варианты сборки**.
2. Выберите **Добавить вариант** и дайте ему имя, например `review`.
3. Выберите **Добавить значение**, затем введите `draft` в поле **Имя** и `true` в поле **Значение**.
4. Выберите **Применить**.
5. Откройте меню компиляции. **Вариант (этот проект)** теперь содержит `review`. Выберите его и компилируйте.

**Без варианта** собирает без каких-либо значений варианта. Выбранный вариант запоминается только на этом компьютере, поэтому соавтор может собрать другой вариант того же проекта. Сами варианты сохраняются в `project.json`. Экспорт тоже использует выбранный вариант.

Значения, которые должна получать каждая сборка, задаются в `typst.inputs` в `project.json`. Когда вариант задаёт значение с тем же именем, побеждает вариант.

## Воспроизводимые сборки

Под **Сборка (этот проект)** в меню компиляции **Воспроизводимая сборка** делает так, что одни и те же исходники дают один и тот же PDF на любом компьютере. Она использует только шрифты проекта и встроенные шрифты Typst и датирует PDF последним коммитом Git. Проект, не являющийся репозиторием Git, получает фиксированную дату 1 января 1970 года.

Это важно, когда PDF должен совпадать по контрольной сумме: для сдачи в архив или сравнения в CI. Нужен Typst 0.12 или новее. Пока она включена, **Использовать системные шрифты** недоступно. По умолчанию используется **Стандартная сборка**.

![Typst компилируется по мере набора: каждая новая строка появляется в PDF.](https://cdn.oleafly.com/images/gifs/desktop/typst-live.gif?v=2)

## Живой предпросмотр с автокомпиляцией

Установите **Автокомпиляция** в положение **Включена** в меню компиляции. В проекте Typst Oleafly затем держит один запущенный процесс Typst. Открытый файл сохраняется через мгновение после того, как вы перестали печатать, Typst компилирует его, и предпросмотр перезагружается на той же позиции прокрутки. Отдельной настройки живого предпросмотра нет: автокомпиляция и есть живой предпросмотр.

Пока Typst запускается, меню показывает «Запуск Typst». Если он останавливается после повторяющихся ошибок, меню сообщает об этом, и следующая правка запускает его снова. **Остановить компиляцию** завершает процесс, и следующая правка тоже запускает его снова. Проекты LaTeX и Markdown обрабатывают автокомпиляцию иначе; см. [Компиляция](/docs/compiling/#auto-compile).

## Сборка из командной строки

Команда `oleafly` собирает проекты без открытия приложения. Она поставляется вместе с Oleafly, а как добавить её в PATH, показано в разделе [Инструмент командной строки](/docs/cli/#install).

Для проекта Typst `oleafly build` и `oleafly watch` читают `project.json` и используют те же настройки, что и приложение: закреплённую версию, скопированные пакеты, папки шрифтов, переключатель системных шрифтов, входные значения и воспроизводимые сборки.

- `--variant review` собирает вариант. Имя, которое проект не определяет, останавливает сборку, и сообщение перечисляет варианты, которые у него есть.
- `--offline` блокирует загрузку пакетов, как офлайн-режим в приложении.
- Закреплённый проект собирается только с этим самым Typst. CLI смотрит на `OLEAFLY_TYPST`, затем на версии, скачанные приложением, затем на `typst` рядом с CLI, затем на ваш `PATH`. Если ни один не сообщает закреплённую версию, сборка останавливается до запуска Typst и рассказывает, как её установить.
- Проект без закрепления использует `OLEAFLY_TYPST`, если он задан. Иначе используется версия по умолчанию, которую вы выбрали в **Настройки → Загрузки** или командой `oleafly typst default`, а если версия по умолчанию не выбрана, встроенный Typst или Typst из вашего `PATH`.
- `oleafly doctor` перечисляет каждый найденный Typst и настройки, которые использовала бы сборка. Он завершается ошибкой, когда закреплённая версия отсутствует.

Если настройка не может примениться к используемому Typst, сборка печатает заметку, например о том, что Typst 0.11.1 не может игнорировать системные шрифты. Ошибки в терминале включают собственные подсказки Typst.

## Конвертируйте проект LaTeX в Typst

Откройте проект LaTeX, нажмите ⌘K (Ctrl+K) и выполните **Преобразовать в проект Typst**. Дайте новому проекту имя и выберите **Преобразовать**. Проект LaTeX остаётся в точности таким, каким был. Oleafly строит из него отдельный проект Typst:

- Pandoc конвертирует текст, формулы, рисунки и таблицы. Если Pandoc ещё не настроен, Oleafly сначала настраивает его.
- Каждый файл, подключённый через `\input`, `\include` или `\subfile`, становится собственным файлом `.typ`.
- Файлы BibTeX копируются без изменений.
- Typst компилирует новый проект, чтобы проверить его.

Отчёт затем сообщает, компилируется ли проект, и подсчитывает сконвертированное: файлы исходника, рисунки, таблицы, выключные формулы, перекрёстные ссылки, формулы, исправленные конвертером математики, и скопированные файлы, а также стиль библиографии, который он выбрал. **Требует внимания** перечисляет то, что нужно исправить вручную: отсутствующий include или изображение, формат изображения, который Typst не может показать, математику, с которой конвертер не справился, стиль BibTeX без соответствия в Typst или метку на одной строке многострочной формулы, которая теперь указывает на всю формулу. Ошибки и предупреждения компиляции ведут к своему файлу и строке.

Выберите **Открыть проект Typst**, чтобы перейти к нему. Новый проект закрепляет вашу версию Typst по умолчанию. Пока Oleafly открыт, команда **Показать отчёт о преобразовании в Typst** в палитре команд возвращает отчёт.

Чтобы конвертировать один файл, а не весь проект, используйте инструмент [Из LaTeX в Typst](/docs/tools/latex-to-typst/) на странице инструментов.

## Связанные страницы

- [Писать в Typst](/docs/writing/typst/) — о панели инструментов и первом документе.
- [Компиляция](/docs/compiling/) — о журналах, меню компиляции и офлайн-режиме.
- [Экспорт и конвертация проекта](/docs/export/#typst-images-and-html) — о PNG, SVG, HTML, PDF/A и PDF/UA.
- [Предпроверка](/docs/preflight/#typst-projects) — о проверках, читающих исходники Typst.
