
Typst — система набора документов, где содержание хранится в разметке, а страница пересобирается сразу после правки исходника. На странице Xeon Live можно скачать Typst бесплатно и перейти к рабочему варианту, а в этом материале разберём веб-редактор, синтаксис, шаблоны, библиографию, автоматизацию и финальный экспорт без попытки превратить Typst в обычный редактор готовых PDF.
Что такое Typst и как устроена рабочая среда
Typst объединяет язык разметки, открытый компилятор и браузерное приложение. Язык задаёт структуру документа и правила оформления, компилятор превращает исходники в конечные файлы, а веб-приложение добавляет редактор, файловую панель, живой предпросмотр и совместную работу. Такой подход особенно удобен для научных статей, отчётов, дипломов, книг, технической документации и повторяемых документов, где номера, ссылки, таблицы и оформление должны обновляться согласованно.
Редактор, предпросмотр и файловая панель

Typst interface © Typst GmbH; screenshot source: Xeon Live
Веб-редактор по умолчанию делит окно на исходный текст и предварительный просмотр. Слева открывается панель файлов проекта, в центральной части редактируется .typ, справа показывается сверстанная страница. Меню View переключает режимы editor-only и preview-only и выносит предпросмотр в отдельное окно. Щелчок по странице помогает перейти к связанному месту исходника, поэтому правка длинной работы не превращается в постоянный поиск нужного абзаца.
В проекте хранятся .typ, текстовые данные, библиография, изображения и шрифты. Для крупной работы практична структура main.typ, отдельные главы, каталог изображений и стилевой модуль. Такой порядок делает источник понятным: main.typ отвечает за сборку, главы — за содержание, а модуль — за единые правила страницы и типографики.
Разметка вместо ручного форматирования
Обычный текст в Typst пишется без функций. Заголовки начинаются со знака равенства, списки — с дефиса или плюса, выделения задаются компактными символами, математические выражения помещаются в математический режим. Решётка переводит строку к функциям и выражениям: через неё добавляют изображения, таблицы, правила оформления, чтение данных и другие элементы. Отсюда главное отличие от Word-подобных редакторов: автор меняет не рамку вокруг каждого абзаца вручную, а правило, по которому все нужные элементы выглядят одинаково.
Typst не предназначен для объектной правки уже готового PDF. Исправления вносятся в .typ и ресурсы проекта, затем документ собирается заново. Для понимания самого формата PDF и его ограничений полезен отдельный материал о структуре и возможностях PDF.
Первый документ: от пустого проекта до готового PDF
Для первого проекта полезнее пройти короткий путь вручную: создать пустой документ, набрать структуру, задать базовые параметры страницы и проверить экспорт. После такого прохода становится ясно, какие действия выполняет разметка, а какие относятся к интерфейсу веб-приложения.
Шаг 1. Создать проект и набрать структуру

Typst interface © Typst GmbH; screenshot source: Xeon Live
- 1. На панели проектов выберите Empty document. Введите название проекта и откройте созданный main.typ.
- 2. В первой строке напишите = Отчёт. Строкой ниже добавьте обычный абзац. Для подраздела используйте == Исходные данные.
- 3. Создайте маркированный список строками, начинающимися с дефиса. Нумерованный список начинается с плюса.
- 4. Добавьте сильное выделение звёздочками и курсив подчёркиваниями. Сразу смотрите, как меняется правая панель.
- 5. Вставьте короткую формулу в знаках доллара. Для первого теста достаточно выражения вида $a^2 + b^2 = c^2$.
- 6. Проверьте, что заголовки попали в структуру документа, список имеет правильные отступы, а формула не выходит за ширину строки.
На этом этапе не настраивайте десятки параметров. Цель — получить минимальный документ, где понятно соответствие между каждой строкой исходника и итоговой страницей. Ошибку разметки проще заметить до подключения пакетов, библиографии и собственных функций.
Шаг 2. Задать страницу, шрифт и абзацы
- 1. В начало main.typ добавьте правило страницы: #set page("a4", margin: 20mm). Оно задаёт формат и поле для последующих страниц.
- 2. Ниже добавьте #set text(size: 11pt, lang: "ru"). Язык важен для переносов и типографических правил русского текста.
- 3. Для основного текста добавьте #set par(justify: true). Оцените плотность набора в предпросмотре, а не по одной строке.
- 4. Для автоматической нумерации заголовков добавьте #set heading(numbering: "1.1"). После этого измените порядок двух разделов и убедитесь, что номера перестроились сами.
- 5. При необходимости вызовите автодополнение сочетанием Ctrl+Space, начните ввод имени параметра и выберите подходящий вариант.
- 6. Просмотрите страницу при масштабе целого листа. Поле должно быть одинаковым по краям, а заголовки не должны оставлять одинокую строку внизу страницы.
Старайтесь задавать параметры глобально только там, где они действительно общие. Локальное оформление помещается в отдельный содержательный блок: правило внутри него действует до конца блока и не меняет остальной документ.
Шаг 3. Выполнить первый экспорт и проверить файл
- 1. Откройте File, затем Export as и PDF. Для первой сборки оставьте диапазон всех страниц.
- 2. Сохраните PDF и откройте его в независимом просмотрщике, а не только во встроенном предпросмотре.
- 3. Выполните поиск по слову из середины документа, скопируйте абзац и формулу, перейдите по внутренней ссылке после её добавления.
- 4. Сверьте количество страниц и номера разделов с веб-предпросмотром. Различие указывает на другой входной файл, шрифт или параметры сборки.
- 5. После проверки сохраните исходник вместе с ресурсами. PDF остаётся результатом, а не единственным экземпляром документа.
Для типовой задачи создания нового файла полезна и общая инструкция Xeon Live по созданию PDF: она помогает отделить работу в Typst от сценариев, где достаточно обычной печати в PDF или офисного приложения.
Структура и оформление: set, show и модульный стиль
Главный рабочий принцип Typst — отделять содержание от правил представления. Set-правила меняют параметры элементов, show-правила меняют способ их отображения, а функции собирают повторяющиеся компоненты. Такой слой оформления особенно полезен в документах, где десятки страниц должны сохранять одинаковую иерархию.
Шаг 1. Собрать базовый набор set-правил

Typst interface © Typst GmbH; screenshot source: Xeon Live
- 1. Оставьте в начале main.typ только действительно глобальные параметры: page, text, par и heading.
- 2. Сначала настройте геометрию страницы, затем основной текст, затем абзац и только после этого заголовки. Такой порядок облегчает поиск причины при изменении переносов.
- 3. Задайте нумерацию заголовков через heading(numbering: ...). Не набирайте номера вручную в тексте.
- 4. Для короткого приложения создайте отдельный содержательный блок и поместите внутрь локальный set text с меньшим размером. После закрытия блока основной стиль восстановится автоматически.
- 5. Поменяйте формат страницы или размер текста и просмотрите весь документ. Смысл проверки — убедиться, что ни один раздел не содержит ручных компенсаций вроде пробелов и пустых строк.
Шаг 2. Применить show-правило там, где параметров недостаточно
- 1. Выберите один класс элементов, например заголовки первого уровня. Используйте селектор heading.where(level: 1), а не правило для всех заголовков.
- 2. Сначала примените show-set вариант для цвета, выравнивания или другого доступного параметра.
- 3. Для полностью собственного представления используйте преобразующее show-правило, которое получает элемент и возвращает новое содержимое.
- 4. После добавления правила создайте два тестовых заголовка разной длины и один заголовок другого уровня. Это показывает область действия и поведение переноса.
- 5. При рекурсивной ошибке сузьте селектор или измените результат так, чтобы он снова не попадал под то же преобразование.
Show-правило не заменяет set там, где нужное свойство уже существует. Чем меньше преобразований применяется к базовым элементам, тем проще поддерживать шаблон и переопределять его локально.
Шаг 3. Вынести оформление в отдельный модуль
- 1. Создайте файл styles.typ и перенесите туда функцию, которая принимает название, автора, дату и основное содержимое.
- 2. Внутри функции расположите правила page, text, heading и повторяемые элементы титульной страницы.
- 3. В main.typ импортируйте функцию через import, затем передайте ей метаданные и содержимое документа.
- 4. Не храните текст главы внутри стилевого файла. Стили должны отвечать за представление, главы — за смысл.
- 5. Измените одно правило в styles.typ и убедитесь, что правка одновременно отражается во всех разделах, которые используют функцию.
- 6. Для серии документов создайте два небольших входных файла с разными метаданными и общей функцией оформления. Это проверяет, что шаблон не зависит от случайных данных одного проекта.
Изображения, таблицы, формулы и перекрёстные ссылки
В техническом документе основная экономия времени появляется после отказа от ручной нумерации. Иллюстрации, таблицы и формулы оформляются как структурные элементы, получают подписи и метки, а текст обращается к ним через ссылки. При перестановке разделов номера и подписи пересчитываются вместе с макетом.
Шаг 1. Загрузить изображение и оформить figure

Typst interface © Typst GmbH; screenshot source: Xeon Live
- 1. Откройте файловую панель и загрузите PNG, JPEG, SVG или другой поддерживаемый ресурс. Используйте короткое имя без случайных суффиксов.
- 2. В исходнике вставьте image с относительным путём. Для иллюстрации с подписью оберните image в figure.
- 3. Добавьте содержательную подпись, которая объясняет, что читатель должен увидеть, а не повторяет название файла.
- 4. Добавьте метку вида <figure-name> сразу после фигуры и обратитесь к ней через @figure-name в тексте.
- 5. Переместите фигуру ниже другого объекта и проверьте, что ссылка показывает новый номер без ручной правки.
- 6. Уменьшите окно предпросмотра и проверьте подпись и ширину. Иллюстрация не должна выходить за поле или становиться нечитаемой.
Растровое изображение стоит хранить в разрешении, соответствующем реальному размеру на странице. Для схем предпочтителен вектор: он остаётся чётким при масштабировании и обычно лучше подходит для печатного PDF.
Шаг 2. Собрать таблицу вручную и из CSV
- 1. Для небольшой таблицы вызовите table, задайте число колонок и последовательно передайте ячейки.
- 2. Сначала проверьте структуру без сложного оформления: заголовок, строки, выравнивание чисел и перенос длинных значений.
- 3. Для данных из файла поместите CSV рядом с исходником и прочитайте его функцией csv. Результат представляет строки данных, которые дальше передаются в table.
- 4. При наличии заголовочной строки отделите её от тела таблицы или используйте представление строк как словарей, когда это упрощает обращение к полям.
- 5. Форматирование чисел выполняйте централизованно. Одинаковое число знаков, единицы измерения и разделители должны вычисляться одной функцией.
- 6. Проверьте длинную строку, пустое значение и максимальное число. Эти три случая быстрее всего показывают, где фиксированная ширина или ручной перенос ломают макет.
Шаг 3. Добавить формулы и ссылки без ручных номеров
- 1. Поместите короткое выражение между знаками доллара. Блочное уравнение оформите отдельно от абзаца.
- 2. Используйте встроенные конструкции для дробей, корней, сумм, интегралов, матриц и систем. Не вставляйте формулу как картинку.
- 3. Включите нумерацию для нужных формул и добавьте метку сразу после выражения.
- 4. В тексте ссылайтесь на метку. После добавления новой формулы выше проверьте автоматическое изменение номера.
- 5. Длинное выражение разбейте по смысловым частям и выровняйте по отношениям. Уменьшение шрифта оставьте последним вариантом.
- 6. В итоговом PDF скопируйте формулу и выполните поиск по соседнему тексту. Это проверяет, что математическая часть не превратилась в растровую вставку.
Библиография, данные и длинные документы
Typst рассчитан на документы, где библиография, главы и данные живут отдельно от оформления. Практический эффект заметен уже в дипломе на несколько десятков страниц: одна запись источника используется во многих местах, главы включаются из отдельных файлов, а оглавление строится по реальной структуре.
Шаг 1. Подключить библиографию и оформить цитаты

Typst interface © Typst GmbH; screenshot source: Xeon Live
- 1. Добавьте в проект BibLaTeX-файл .bib или библиографию Hayagriva в YAML.
- 2. В конце документа вызовите bibliography с путём к файлу. После этого записи становятся доступными для ссылок.
- 3. В месте цитирования используйте @ и идентификатор записи из библиографии. Для точной формы доступен вызов cite.
- 4. Выберите стиль оформления библиографии встроенным именем или подключите CSL-файл, когда издатель требует собственный стандарт.
- 5. Проверьте несколько разных типов источников: статью, книгу и веб-материал. Сверьте авторов, год, заглавие и порядок элементов.
- 6. Удалите одну цитату из текста и убедитесь, что ненужная запись не остаётся в итоговом списке, когда она больше нигде не используется.
При работе с большой библиотекой полезен менеджер источников. На Xeon Live есть отдельный обзор Zotero для управления источниками и PDF. Веб-приложение Typst поддерживает синхронизацию библиографии с Zotero и Mendeley; создание синхронизируемого файла относится к Typst Pro, а после создания файл работает как обычная BibLaTeX-библиография проекта.
Шаг 2. Разделить большую работу на файлы
- 1. Оставьте main.typ точкой сборки и создайте каталог chapters для глав.
- 2. Подключайте содержимое глав через include. Для функций, переменных и стилевых модулей используйте import.
- 3. Храните иллюстрации в отдельном каталоге и используйте относительные пути. Переименование выполняйте вместе с обновлением ссылок в исходниках.
- 4. Создайте оглавление через outline, а нумерацию заголовков — через heading. Не набирайте страницу в оглавлении вручную.
- 5. Добавьте отдельный входной файл для проверки одной главы. Он импортирует тот же стиль и включает только нужную часть.
- 6. Перед финальной сборкой компилируйте и полный документ, и вспомогательный вход. Ошибка пути, скрытая в одной главе, должна обнаружиться до сдачи.
Шаг 3. Строить отчёт из CSV и JSON
- 1. Разместите исходные данные в CSV или JSON рядом с проектом и закрепите понятную схему полей.
- 2. Прочитайте файл функцией csv или json и сохраните результат в переменную.
- 3. Сформируйте строки таблицы из одного массива данных. Итоговые показатели и подписи должны вычисляться из того же источника.
- 4. Добавьте обработку пустого набора данных: документ обязан сформировать понятный пустой раздел вместо падения в середине таблицы.
- 5. Сравните одну строку исходного файла с таблицей в PDF, затем проверьте сумму или количество элементов независимо.
- 6. Для ежемесячной серии передавайте период и служебные параметры через входные значения среды сборки, а не редактируйте шаблон перед каждым выпуском.
Шаблоны и пакеты Typst Universe
Шаблоны сокращают старт проекта, а пакеты выносят повторяемые функции и оформление в версионируемую зависимость. Эти механизмы решают разные задачи: шаблон создаёт начальную структуру, пакет подключается к уже существующему документу и централизованно обновляет общий код. Частные пакеты в облачном приложении относятся к Typst Pro, тогда как публичные пакеты Typst Universe подключаются через пространство @preview.
Шаг 1. Создать документ из готового шаблона
- 1. На панели проектов откройте Start from template и выберите подходящий вариант по типу работы.
- 2. Просмотрите структуру шаблона до заполнения текста: main.typ, стилевые файлы, каталоги, пример библиографии и обязательные метаданные.
- 3. Сразу замените демонстрационные название и авторов, затем соберите пустую версию. Так видны обязательные поля и ошибки конфигурации.
- 4. Не переписывайте внутренний стиль под каждый абзац. Сначала найдите публичные параметры шаблона и его основную функцию.
- 5. После изменения требований проверьте титул, заголовки, таблицы, формулы и библиографию. Правка шаблона способна изменить весь документ.
Шаг 2. Подключить пакет и закрепить версию
- 1. Выберите пакет в Typst Universe и изучите его документацию, лицензию и пример использования.
- 2. Добавьте import с пространством @preview, именем пакета и точной версией.
- 3. Импортируйте только используемые функции либо подключите модуль целиком и обращайтесь к функциям через его имя.
- 4. Соберите контрольный PDF и сохраните его перед обновлением пакета.
- 5. Обновляйте одну зависимость за раз. После изменения версии сравните страницы с таблицами, фигурами, формулами и оглавлением.
- 6. При несовместимости верните прежнюю версию, затем прочитайте изменения API и перенесите вызовы осознанно.
Шаг 3. Собрать собственный пакет оформления

Typst interface © Typst GmbH; screenshot source: Xeon Live
- 1. Откройте File > Package project или команду Create package manifest. В корне появится typst.toml.
- 2. Укажите имя пакета, версию и точку входа. Категории и дисциплины заполняйте по реальному назначению.
- 3. Поместите публичные функции в точку входа, а внутренние помощники — в отдельные файлы.
- 4. Создайте чистый тестовый проект и импортируйте пакет так, как это сделает другой документ. Скрытая зависимость от локального файла проявится сразу.
- 5. Перед новой публикацией измените версию и соберите набор контрольных документов. Старые версии не удаляйте из рабочего процесса, пока на них ссылаются утверждённые материалы.
Совместная работа, комментарии и презентация
Веб-приложение добавляет к языку разметки командные функции: совместное редактирование, уровни доступа, комментарии и режим презентации. Комментарии, приглашение по электронной почте и встроенный режим презентации относятся к возможностям Typst Pro. Для рабочего процесса важно разделять правку исходника и обсуждение: замечание рецензента не должно случайно становиться текстом документа.

Typst interface © Typst GmbH; screenshot source: Xeon Live
Шаг 1. Выдать доступ с правильной ролью
- 1. Откройте настройки общего доступа проекта.
- 2. Для соавтора, который меняет исходник, назначьте право записи. Для рецензента используйте режим Review, когда требуется обсуждение без правки текста.
- 3. Перед отправкой ссылки повторно проверьте выбранный уровень. Право записи не подходит для публичного просмотра.
- 4. После завершения внешнего рецензирования отключите лишний доступ и оставьте только действующих участников.
- 5. Для командного проекта договоритесь, кто редактирует стилевой модуль. Одна строка глобального set или show меняет множество страниц.

Typst interface © Typst GmbH; screenshot source: Xeon Live
Шаг 2. Создать, обсудить и закрыть комментарий
- 1. Выделите точный диапазон исходного текста и нажмите кнопку добавления комментария.
- 2. Формулируйте замечание так, чтобы смысл сохранялся после небольшого перемещения текста: укажите проблему и желаемый результат.
- 3. Используйте ответы внутри одной ветки, когда обсуждение относится к тому же месту.
- 4. После исправления нажмите Resolve. Разрешённое обсуждение сохраняется для истории и исчезает из активного списка.
- 5. Удаляйте комментарий только тогда, когда история больше не нужна. Удаление необратимо, а resolved-состояние допускает возврат.
- 6. Экспортируйте PDF и убедитесь, что редакционные комментарии не попали в документ.

Typst interface © Typst GmbH; screenshot source: Xeon Live
Шаг 3. Подготовить документ к показу
- 1. Откройте документ, рассчитанный на слайды, и перейдите в режим презентации веб-приложения.
- 2. Проверьте соотношение крупного текста, иллюстраций и свободного места на каждом слайде.
- 3. В Speaker Mode используйте правую часть окна для просмотра следующего слайда, текущего времени и таймера. Встроенных заметок докладчика в текущем режиме презентации нет.
- 4. Пройдите презентацию от начала до конца с клавиатуры и проверьте переходы между страницами.
- 5. Сохраните PDF-версию как резервный вариант показа. Она не зависит от браузерной сессии и сохраняет рассчитанный макет.

Screenshot © Typst GmbH, typst.app documentation
CLI, автоматизация и воспроизводимая сборка
Командная строка нужна там, где PDF собирается без браузера: на рабочей станции, в скрипте, в CI или внутри генератора отчётов. Базовые команды compile и watch покрывают ручную сборку и непрерывное обновление, а дополнительные параметры управляют шрифтами, входными значениями и форматом экспорта.
Шаг 1. Собрать документ командой compile

Typst interface © Typst GmbH; screenshot source: Xeon Live
- 1. Установите официальный CLI-компилятор и откройте терминал в каталоге проекта.
- 2. Выполните typst compile main.typ. По умолчанию рядом появится main.pdf.
- 3. Для собственного имени укажите второй путь: typst compile main.typ build/report.pdf.
- 4. При ошибке прочитайте файл, строку и диагностическое сообщение. Не запускайте повторную сборку до исправления причины.
- 5. Откройте полученный PDF и сравните его с контрольным файлом веб-приложения. Различия чаще связаны со шрифтами, версиями пакетов или другим набором входных данных.
Шаг 2. Использовать watch во время редактирования
- 1. Запустите typst watch main.typ.
- 2. Оставьте процесс работающим и измените абзац или параметр страницы.
- 3. Убедитесь, что PDF пересобрался после сохранения исходника. Инкрементальная сборка ускоряет повторные изменения.
- 4. При переименовании ресурса следите за сообщениями File not found. Watch показывает ошибку сразу после сохранения.
- 5. Перед финальным выпуском остановите watch и выполните отдельную чистую compile-команду. Такой проход фиксирует итог без состояния предыдущей сессии.
Шаг 3. Зафиксировать шрифты, пакеты и входные данные
- 1. Выполните typst fonts и запишите точные имена гарнитур, которые использует документ.
- 2. Дополнительный каталог передавайте через --font-path. В сборочной среде используйте тот же набор файлов шрифтов.
- 3. Во всех импортах пакетов оставьте точные версии. Обновление выполняйте отдельной задачей, а не одновременно с редактурой текста.
- 4. Данные CSV, JSON и библиографию храните рядом с исходниками либо получайте предсказуемым этапом до компиляции.
- 5. Для утверждённого выпуска сохраните исходники, список зависимостей, набор шрифтов и контрольный PDF.
- 6. При обновлении компилятора сравните страницы с формулами, таблицами, переносами, оглавлением и колонтитулами. Размер файла сам по себе не подтверждает одинаковый макет.
Шаг 4. Синхронизировать веб-проект через Git
- 1. В настройках аккаунта подключите GitHub или GitLab, затем откройте настройки конкретного проекта.
- 2. В разделе Version control свяжите проект с заранее созданным репозиторием или пустым каталогом репозитория.
- 3. Перед началом работы выполните pull и просмотрите изменения, пришедшие из удалённой истории.
- 4. После правки исходников нажмите push, введите содержательное сообщение коммита и отправьте изменения.
- 5. При изменении двоичного файла с двух сторон выберите нужную версию осознанно: изображения и другие бинарные ресурсы не объединяются как текст.
- 6. Синхронизация Git в веб-приложении остаётся экспериментальной; для выпуска сохраняйте обычную локальную историю репозитория и контрольный PDF.

Screenshot © Typst GmbH, typst.app documentation

Screenshot © Typst GmbH, typst.app documentation

Screenshot © Typst GmbH, typst.app documentation
Для конвейеров, где исходный материал приходит в другой разметке, полезно сопоставить подход Typst с Pandoc для конвертации документов и разметки. Pandoc умеет использовать Typst как один из PDF-движков, но сам по себе решает более широкую задачу преобразования форматов.
Экспорт, диагностика и финальная проверка
Финальная стадия — не просто нажатие кнопки загрузки. Экспорт определяет диапазон страниц, формат и PDF-профиль, а проверка подтверждает читаемость, ссылки, текстовый слой и воспроизводимость. Для серьёзного документа этот этап лучше выполнять по одному и тому же чек-листу.
Шаг 1. Настроить PDF и диапазон страниц

Typst interface © Typst GmbH; screenshot source: Xeon Live
- 1. Откройте Export & Preview через File > Export as > PDF или стрелку рядом с быстрым экспортом.
- 2. Для полного документа оставьте All pages. Для проверки части выберите Current page или Custom ranges и задайте нужные номера.
- 3. Выберите версию PDF и дополнительный стандарт только по требованиям архива, издателя или процесса. По умолчанию Typst формирует PDF 1.7.
- 4. Не отключайте теги PDF без отдельной причины. По умолчанию Typst создаёт Tagged PDF как базу для доступности.
- 5. Скачайте файл и откройте его внешним просмотрщиком. Проверьте количество страниц, метаданные, поиск, копирование текста и внутренние переходы.
Шаг 2. Выбрать PNG, SVG или HTML вместо PDF
- 1. Для растрового изображения страницы выберите PNG. Проверьте разрешение, потому что оно напрямую влияет на детализацию и размер файла.
- 2. Для векторной страницы выберите SVG. Многостраничный документ экспортируется набором файлов, а не одним многостраничным SVG.
- 3. HTML в текущей линии Typst относится к экспериментальному направлению. В веб-приложении его предпросмотр включается в настройках проекта.
- 4. Для HTML отдельно проверьте шаблон, колонтитулы, абсолютное позиционирование и элементы, рассчитанные только на печатную страницу.
- 5. Не считайте совпадение PDF и HTML гарантированным. Семантическое содержание удобно держать общим, а оформление для paged и web разделять по цели.
Шаг 3. Найти и устранить типовые ошибки
- 1. При синтаксической ошибке сначала проверьте незакрытые круглые, квадратные и фигурные скобки, затем запятые между именованными параметрами.
- 2. При Unknown variable проверьте написание имени, область видимости и import. Функция, определённая внутри локального блока, снаружи недоступна.
- 3. При File not found проверьте регистр имени, расширение и относительный путь от файла, где выполняется обращение.
- 4. При предупреждении о шрифте выполните typst fonts и используйте точное имя семейства. Имя файла гарнитуры не обязано совпадать с её семейным именем.
- 5. При неизвестной ссылке проверьте метку объекта или идентификатор библиографической записи. Дубликаты меток устраняются переименованием одного объекта.
- 6. При переполнении страницы найдите конкретную широкую таблицу, неразрывную строку, картинку или контейнер. Глобальное уменьшение текста скрывает причину и ухудшает весь документ.
Шаг 4. Провести приёмку итогового PDF
- 1. Просмотрите весь документ в режиме целой страницы и отметьте пустые полосы, одиночные строки, неудачные разрывы и страницы с иной плотностью.
- 2. Повторите просмотр при масштабе 100 процентов. Проверьте резкость растров, толщину линий, мелкие подписи и математические индексы.
- 3. Перейдите по нескольким ссылкам из текста на формулы, рисунки и разделы. Номера должны совпадать с подписями.
- 4. Проверьте оглавление, библиографию, номера страниц, начало каждой главы и последние страницы приложений.
- 5. Выполните поиск по редкому слову, скопируйте абзац и формулу в текстовый редактор. Это выявляет проблемы текстового слоя.
- 6. Сохраните финальный PDF рядом с исходниками и данными выпуска. Следующую редакцию собирайте из тех же источников, а не правьте экспорт вручную.
Почему PDF собрался, но выглядит иначе у коллеги?
Проверьте версию компилятора, версии пакетов, входные данные и набор шрифтов. Различие гарнитуры меняет ширину строк и переносы страниц.
Почему комментарии не появились в PDF?
Рецензентские комментарии относятся к интерфейсу совместной работы и специально не включаются в экспорт. Замечание, которое должно попасть в документ, оформляется обычным содержимым.
Почему изображение не находится?
Проверьте регистр имени, расширение и относительный путь от текущего файла. После перемещения ресурса обновите все обращения к нему.
Почему библиографическая ссылка остаётся неизвестной?
Проверьте запись в .bib или YAML, её идентификатор и наличие bibliography в собираемом документе. После исправления пересоберите проект.
Почему HTML отличается от PDF?
HTML-экспорт остаётся экспериментальным и использует другую модель представления. Печатные элементы и сложный абсолютный макет требуют отдельной проверки.
Почему готовый PDF нельзя исправить прямо в Typst?
Typst работает с исходной разметкой и пересобирает результат. Для объектной правки существующего PDF используется отдельный PDF-редактор.
Плюсы, минусы, альтернативы и практический выбор
Typst особенно силён там, где документ имеет структуру и должен воспроизводимо пересобираться: отчёты, статьи, дипломы, книги, спецификации, презентации и документы из данных. Его слабое место — задачи, где исходником уже служит чужой готовый PDF и требуется вручную двигать объекты, стирать текст или редактировать страницу без исходной разметки.
Что в Typst особенно полезно

Typst interface © Typst GmbH; screenshot source: Xeon Live
Плюсы
- Живой предпросмотр связывает исходник и сверстанную страницу и ускоряет цикл правки.
- Короткий синтаксис покрывает обычный текст, заголовки, списки, формулы, таблицы, ссылки и библиографию.
- Set- и show-правила отделяют оформление от содержания и позволяют менять стиль целого документа из одного места.
- Встроенные функции чтения CSV, JSON, YAML, TOML и XML подходят для автоматизированных отчётов и документов из данных.
- CLI поддерживает compile и watch, поэтому сборка встраивается в локальные скрипты и CI.
- PDF остаётся основным зрелым результатом, а PNG и SVG доступны для отдельных страниц; HTML развивается как отдельное экспериментальное направление.
- Шаблоны и пакеты уменьшают дублирование и позволяют фиксировать версии общего оформления.
Минусы
- Для уверенной работы нужно освоить разметку, функции и правила области видимости; визуальное перетаскивание элементов не является основной моделью.
- Готовый PDF не редактируется как набор объектов: правка выполняется в исходнике с повторной сборкой.
- Сложное show-правило или пользовательская функция усложняют проект не меньше обычного программного кода и требуют дисциплины именования.
- Различия в шрифтах, версиях пакетов и компилятора отражаются на переносах и числе страниц, поэтому серьёзному проекту нужна воспроизводимая среда.
- HTML-экспорт остаётся экспериментальным и не гарантирует полного совпадения с печатным макетом.
- Некоторые командные возможности облачного приложения относятся к расширенным функциям сервиса, тогда как язык и компилятор доступны отдельно как открытый проект.
Кому подойдёт
- Авторам научных и технических документов, которым нужны формулы, библиография, перекрёстные ссылки и стабильная нумерация.
- Командам, которые хотят хранить содержание и оформление в текстовых исходниках и контролировать изменения через Git.
- Аналитикам и разработчикам, формирующим регулярные отчёты из CSV, JSON и других структурированных данных.
- Редакциям и организациям с повторяемым корпоративным шаблоном для большого числа документов.
- Пользователям LaTeX, которым нужен более компактный синтаксис и быстрый живой предпросмотр.
Кому не подойдёт
- Пользователям, которым нужно править только готовые чужие PDF без исходников.
- Задачам, где основная работа состоит в свободном визуальном размещении объектов мышью и постоянной ручной доводке каждой страницы.
- Процессам, где веб-страница является единственным целевым форматом и требуется полностью зрелая HTML-цепочка без экспериментальных ограничений.
Краткое сравнение с реальными альтернативами
LaTeX остаётся зрелой экосистемой научной верстки с огромным количеством классов и пакетов, но его синтаксис и диагностические сообщения обычно требуют большего порога входа. Typst ориентируется на более короткую разметку, быстрый компилятор и единый встроенный язык для оформления и автоматизации. Для издательского процесса с обязательным LaTeX-классом решение диктует редакция, а для собственного нового шаблона Typst сокращает число служебных конструкций.
Microsoft Word и Google Docs удобнее для свободной офисной правки и привычного WYSIWYG-подхода. Typst выигрывает в повторяемом наборе, автоматической нумерации, библиографии, документе из данных и текстовой истории изменений. Выбор определяется источником истины: визуальный файл удобнее держать в офисном редакторе, структурированный исходник — в Typst.
Pandoc решает прежде всего задачу преобразования между форматами и разметками. Он подходит как конвейер, где один источник должен превращаться в разные представления, а Typst выступает одним из движков для качественного PDF. Сам Typst удобнее, когда макет, формулы, автоматизация и структура документа проектируются прямо в его языке.
Практические рекомендации по сценариям
- Для статьи или диплома. Начните с требований издателя или вуза, выберите проверенный шаблон либо небольшой собственный модуль, заведите библиографию в начале работы и ставьте метки у формул, рисунков и таблиц сразу.
- Для регулярного отчёта. Отделите данные от разметки, загружайте CSV или JSON, централизуйте форматирование чисел и проверяйте контрольные суммы перед экспортом.
- Для книги. Разделите главы на файлы, храните глобальные правила в одном месте, создайте вспомогательные входные файлы для отдельных глав и фиксируйте набор шрифтов.
- Для командной работы. Разведите права записи и рецензирования, сохраняйте обсуждения через Resolve, а изменения общего стилевого модуля согласовывайте отдельно.
- Для автоматической сборки. Фиксируйте компилятор, пакеты, шрифты и данные; запускайте чистую compile-сборку перед выпуском и храните контрольный PDF вместе с исходниками.
- Для существующего PDF. Не переносите документ в Typst ради одной правки страницы. Используйте редактор PDF либо найдите исходный документ, внесите изменения там и сформируйте новый файл.
Итоговая логика проста: Typst полезен как система создания и воспроизводимой сборки документов, а не как универсальный редактор уже сформированных файлов. Лучший результат даёт проект, где структура, стиль, данные и библиография хранятся отдельно, а PDF остаётся проверяемым выходным артефактом.