Typst: где скачать и как пользоваться

Typst: создание структурированного документа из разметки с экспортом в PDF

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

Что такое Typst и как устроена рабочая среда

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
Пустой документ подходит для знакомства с синтаксисом без скрытых правил шаблона.
Typst interface © Typst GmbH; screenshot source: Xeon Live
  1. 1. На панели проектов выберите Empty document. Введите название проекта и откройте созданный main.typ.
  2. 2. В первой строке напишите = Отчёт. Строкой ниже добавьте обычный абзац. Для подраздела используйте == Исходные данные.
  3. 3. Создайте маркированный список строками, начинающимися с дефиса. Нумерованный список начинается с плюса.
  4. 4. Добавьте сильное выделение звёздочками и курсив подчёркиваниями. Сразу смотрите, как меняется правая панель.
  5. 5. Вставьте короткую формулу в знаках доллара. Для первого теста достаточно выражения вида $a^2 + b^2 = c^2$.
  6. 6. Проверьте, что заголовки попали в структуру документа, список имеет правильные отступы, а формула не выходит за ширину строки.

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

Шаг 2. Задать страницу, шрифт и абзацы

  1. 1. В начало main.typ добавьте правило страницы: #set page("a4", margin: 20mm). Оно задаёт формат и поле для последующих страниц.
  2. 2. Ниже добавьте #set text(size: 11pt, lang: "ru"). Язык важен для переносов и типографических правил русского текста.
  3. 3. Для основного текста добавьте #set par(justify: true). Оцените плотность набора в предпросмотре, а не по одной строке.
  4. 4. Для автоматической нумерации заголовков добавьте #set heading(numbering: "1.1"). После этого измените порядок двух разделов и убедитесь, что номера перестроились сами.
  5. 5. При необходимости вызовите автодополнение сочетанием Ctrl+Space, начните ввод имени параметра и выберите подходящий вариант.
  6. 6. Просмотрите страницу при масштабе целого листа. Поле должно быть одинаковым по краям, а заголовки не должны оставлять одинокую строку внизу страницы.

Старайтесь задавать параметры глобально только там, где они действительно общие. Локальное оформление помещается в отдельный содержательный блок: правило внутри него действует до конца блока и не меняет остальной документ.

Шаг 3. Выполнить первый экспорт и проверить файл

  1. 1. Откройте File, затем Export as и PDF. Для первой сборки оставьте диапазон всех страниц.
  2. 2. Сохраните PDF и откройте его в независимом просмотрщике, а не только во встроенном предпросмотре.
  3. 3. Выполните поиск по слову из середины документа, скопируйте абзац и формулу, перейдите по внутренней ссылке после её добавления.
  4. 4. Сверьте количество страниц и номера разделов с веб-предпросмотром. Различие указывает на другой входной файл, шрифт или параметры сборки.
  5. 5. После проверки сохраните исходник вместе с ресурсами. PDF остаётся результатом, а не единственным экземпляром документа.

Для типовой задачи создания нового файла полезна и общая инструкция Xeon Live по созданию PDF: она помогает отделить работу в Typst от сценариев, где достаточно обычной печати в PDF или офисного приложения.

Структура и оформление: set, show и модульный стиль

Главный рабочий принцип Typst — отделять содержание от правил представления. Set-правила меняют параметры элементов, show-правила меняют способ их отображения, а функции собирают повторяющиеся компоненты. Такой слой оформления особенно полезен в документах, где десятки страниц должны сохранять одинаковую иерархию.

Шаг 1. Собрать базовый набор set-правил

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

Шаг 2. Применить show-правило там, где параметров недостаточно

  1. 1. Выберите один класс элементов, например заголовки первого уровня. Используйте селектор heading.where(level: 1), а не правило для всех заголовков.
  2. 2. Сначала примените show-set вариант для цвета, выравнивания или другого доступного параметра.
  3. 3. Для полностью собственного представления используйте преобразующее show-правило, которое получает элемент и возвращает новое содержимое.
  4. 4. После добавления правила создайте два тестовых заголовка разной длины и один заголовок другого уровня. Это показывает область действия и поведение переноса.
  5. 5. При рекурсивной ошибке сузьте селектор или измените результат так, чтобы он снова не попадал под то же преобразование.

Show-правило не заменяет set там, где нужное свойство уже существует. Чем меньше преобразований применяется к базовым элементам, тем проще поддерживать шаблон и переопределять его локально.

Шаг 3. Вынести оформление в отдельный модуль

  1. 1. Создайте файл styles.typ и перенесите туда функцию, которая принимает название, автора, дату и основное содержимое.
  2. 2. Внутри функции расположите правила page, text, heading и повторяемые элементы титульной страницы.
  3. 3. В main.typ импортируйте функцию через import, затем передайте ей метаданные и содержимое документа.
  4. 4. Не храните текст главы внутри стилевого файла. Стили должны отвечать за представление, главы — за смысл.
  5. 5. Измените одно правило в styles.typ и убедитесь, что правка одновременно отражается во всех разделах, которые используют функцию.
  6. 6. Для серии документов создайте два небольших входных файла с разными метаданными и общей функцией оформления. Это проверяет, что шаблон не зависит от случайных данных одного проекта.

Изображения, таблицы, формулы и перекрёстные ссылки

В техническом документе основная экономия времени появляется после отказа от ручной нумерации. Иллюстрации, таблицы и формулы оформляются как структурные элементы, получают подписи и метки, а текст обращается к ним через ссылки. При перестановке разделов номера и подписи пересчитываются вместе с макетом.

Шаг 1. Загрузить изображение и оформить figure

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

Растровое изображение стоит хранить в разрешении, соответствующем реальному размеру на странице. Для схем предпочтителен вектор: он остаётся чётким при масштабировании и обычно лучше подходит для печатного PDF.

Шаг 2. Собрать таблицу вручную и из CSV

  1. 1. Для небольшой таблицы вызовите table, задайте число колонок и последовательно передайте ячейки.
  2. 2. Сначала проверьте структуру без сложного оформления: заголовок, строки, выравнивание чисел и перенос длинных значений.
  3. 3. Для данных из файла поместите CSV рядом с исходником и прочитайте его функцией csv. Результат представляет строки данных, которые дальше передаются в table.
  4. 4. При наличии заголовочной строки отделите её от тела таблицы или используйте представление строк как словарей, когда это упрощает обращение к полям.
  5. 5. Форматирование чисел выполняйте централизованно. Одинаковое число знаков, единицы измерения и разделители должны вычисляться одной функцией.
  6. 6. Проверьте длинную строку, пустое значение и максимальное число. Эти три случая быстрее всего показывают, где фиксированная ширина или ручной перенос ломают макет.

Шаг 3. Добавить формулы и ссылки без ручных номеров

  1. 1. Поместите короткое выражение между знаками доллара. Блочное уравнение оформите отдельно от абзаца.
  2. 2. Используйте встроенные конструкции для дробей, корней, сумм, интегралов, матриц и систем. Не вставляйте формулу как картинку.
  3. 3. Включите нумерацию для нужных формул и добавьте метку сразу после выражения.
  4. 4. В тексте ссылайтесь на метку. После добавления новой формулы выше проверьте автоматическое изменение номера.
  5. 5. Длинное выражение разбейте по смысловым частям и выровняйте по отношениям. Уменьшение шрифта оставьте последним вариантом.
  6. 6. В итоговом PDF скопируйте формулу и выполните поиск по соседнему тексту. Это проверяет, что математическая часть не превратилась в растровую вставку.

Библиография, данные и длинные документы

Typst рассчитан на документы, где библиография, главы и данные живут отдельно от оформления. Практический эффект заметен уже в дипломе на несколько десятков страниц: одна запись источника используется во многих местах, главы включаются из отдельных файлов, а оглавление строится по реальной структуре.

Шаг 1. Подключить библиографию и оформить цитаты

Файловое меню Typst с созданием манифеста и синхронизацией библиографии
Файловое меню включает создание манифеста и команды синхронизации библиографии в веб-приложении.
Typst interface © Typst GmbH; screenshot source: Xeon Live
  1. 1. Добавьте в проект BibLaTeX-файл .bib или библиографию Hayagriva в YAML.
  2. 2. В конце документа вызовите bibliography с путём к файлу. После этого записи становятся доступными для ссылок.
  3. 3. В месте цитирования используйте @ и идентификатор записи из библиографии. Для точной формы доступен вызов cite.
  4. 4. Выберите стиль оформления библиографии встроенным именем или подключите CSL-файл, когда издатель требует собственный стандарт.
  5. 5. Проверьте несколько разных типов источников: статью, книгу и веб-материал. Сверьте авторов, год, заглавие и порядок элементов.
  6. 6. Удалите одну цитату из текста и убедитесь, что ненужная запись не остаётся в итоговом списке, когда она больше нигде не используется.

При работе с большой библиотекой полезен менеджер источников. На Xeon Live есть отдельный обзор Zotero для управления источниками и PDF. Веб-приложение Typst поддерживает синхронизацию библиографии с Zotero и Mendeley; создание синхронизируемого файла относится к Typst Pro, а после создания файл работает как обычная BibLaTeX-библиография проекта.

Шаг 2. Разделить большую работу на файлы

  1. 1. Оставьте main.typ точкой сборки и создайте каталог chapters для глав.
  2. 2. Подключайте содержимое глав через include. Для функций, переменных и стилевых модулей используйте import.
  3. 3. Храните иллюстрации в отдельном каталоге и используйте относительные пути. Переименование выполняйте вместе с обновлением ссылок в исходниках.
  4. 4. Создайте оглавление через outline, а нумерацию заголовков — через heading. Не набирайте страницу в оглавлении вручную.
  5. 5. Добавьте отдельный входной файл для проверки одной главы. Он импортирует тот же стиль и включает только нужную часть.
  6. 6. Перед финальной сборкой компилируйте и полный документ, и вспомогательный вход. Ошибка пути, скрытая в одной главе, должна обнаружиться до сдачи.

Шаг 3. Строить отчёт из CSV и JSON

  1. 1. Разместите исходные данные в CSV или JSON рядом с проектом и закрепите понятную схему полей.
  2. 2. Прочитайте файл функцией csv или json и сохраните результат в переменную.
  3. 3. Сформируйте строки таблицы из одного массива данных. Итоговые показатели и подписи должны вычисляться из того же источника.
  4. 4. Добавьте обработку пустого набора данных: документ обязан сформировать понятный пустой раздел вместо падения в середине таблицы.
  5. 5. Сравните одну строку исходного файла с таблицей в PDF, затем проверьте сумму или количество элементов независимо.
  6. 6. Для ежемесячной серии передавайте период и служебные параметры через входные значения среды сборки, а не редактируйте шаблон перед каждым выпуском.

Шаблоны и пакеты Typst Universe

Шаблоны сокращают старт проекта, а пакеты выносят повторяемые функции и оформление в версионируемую зависимость. Эти механизмы решают разные задачи: шаблон создаёт начальную структуру, пакет подключается к уже существующему документу и централизованно обновляет общий код. Частные пакеты в облачном приложении относятся к Typst Pro, тогда как публичные пакеты Typst Universe подключаются через пространство @preview.

Шаг 1. Создать документ из готового шаблона

  1. 1. На панели проектов откройте Start from template и выберите подходящий вариант по типу работы.
  2. 2. Просмотрите структуру шаблона до заполнения текста: main.typ, стилевые файлы, каталоги, пример библиографии и обязательные метаданные.
  3. 3. Сразу замените демонстрационные название и авторов, затем соберите пустую версию. Так видны обязательные поля и ошибки конфигурации.
  4. 4. Не переписывайте внутренний стиль под каждый абзац. Сначала найдите публичные параметры шаблона и его основную функцию.
  5. 5. После изменения требований проверьте титул, заголовки, таблицы, формулы и библиографию. Правка шаблона способна изменить весь документ.

Шаг 2. Подключить пакет и закрепить версию

  1. 1. Выберите пакет в Typst Universe и изучите его документацию, лицензию и пример использования.
  2. 2. Добавьте import с пространством @preview, именем пакета и точной версией.
  3. 3. Импортируйте только используемые функции либо подключите модуль целиком и обращайтесь к функциям через его имя.
  4. 4. Соберите контрольный PDF и сохраните его перед обновлением пакета.
  5. 5. Обновляйте одну зависимость за раз. После изменения версии сравните страницы с таблицами, фигурами, формулами и оглавлением.
  6. 6. При несовместимости верните прежнюю версию, затем прочитайте изменения API и перенесите вызовы осознанно.

Шаг 3. Собрать собственный пакет оформления

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

Совместная работа, комментарии и презентация

Веб-приложение добавляет к языку разметки командные функции: совместное редактирование, уровни доступа, комментарии и режим презентации. Комментарии, приглашение по электронной почте и встроенный режим презентации относятся к возможностям Typst Pro. Для рабочего процесса важно разделять правку исходника и обсуждение: замечание рецензента не должно случайно становиться текстом документа.

Управление командой и участниками в Typst
Командная область Typst показывает участников и общие проекты.
Typst interface © Typst GmbH; screenshot source: Xeon Live

Шаг 1. Выдать доступ с правильной ролью

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

Шаг 2. Создать, обсудить и закрыть комментарий

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

Шаг 3. Подготовить документ к показу

  1. 1. Откройте документ, рассчитанный на слайды, и перейдите в режим презентации веб-приложения.
  2. 2. Проверьте соотношение крупного текста, иллюстраций и свободного места на каждом слайде.
  3. 3. В Speaker Mode используйте правую часть окна для просмотра следующего слайда, текущего времени и таймера. Встроенных заметок докладчика в текущем режиме презентации нет.
  4. 4. Пройдите презентацию от начала до конца с клавиатуры и проверьте переходы между страницами.
  5. 5. Сохраните PDF-версию как резервный вариант показа. Она не зависит от браузерной сессии и сохраняет рассчитанный макет.
Официальный экран Speaker Mode в Typst
Speaker Mode показывает текущий и следующий слайды, время и таймер; встроенных заметок докладчика нет.
Screenshot © Typst GmbH, typst.app documentation

CLI, автоматизация и воспроизводимая сборка

Командная строка нужна там, где PDF собирается без браузера: на рабочей станции, в скрипте, в CI или внутри генератора отчётов. Базовые команды compile и watch покрывают ручную сборку и непрерывное обновление, а дополнительные параметры управляют шрифтами, входными значениями и форматом экспорта.

Шаг 1. Собрать документ командой compile

Поиск и замена в редакторе Typst
Поиск и замена полезны при рефакторинге большого исходника перед автоматической сборкой.
Typst interface © Typst GmbH; screenshot source: Xeon Live
  1. 1. Установите официальный CLI-компилятор и откройте терминал в каталоге проекта.
  2. 2. Выполните typst compile main.typ. По умолчанию рядом появится main.pdf.
  3. 3. Для собственного имени укажите второй путь: typst compile main.typ build/report.pdf.
  4. 4. При ошибке прочитайте файл, строку и диагностическое сообщение. Не запускайте повторную сборку до исправления причины.
  5. 5. Откройте полученный PDF и сравните его с контрольным файлом веб-приложения. Различия чаще связаны со шрифтами, версиями пакетов или другим набором входных данных.

Шаг 2. Использовать watch во время редактирования

  1. 1. Запустите typst watch main.typ.
  2. 2. Оставьте процесс работающим и измените абзац или параметр страницы.
  3. 3. Убедитесь, что PDF пересобрался после сохранения исходника. Инкрементальная сборка ускоряет повторные изменения.
  4. 4. При переименовании ресурса следите за сообщениями File not found. Watch показывает ошибку сразу после сохранения.
  5. 5. Перед финальным выпуском остановите watch и выполните отдельную чистую compile-команду. Такой проход фиксирует итог без состояния предыдущей сессии.

Шаг 3. Зафиксировать шрифты, пакеты и входные данные

  1. 1. Выполните typst fonts и запишите точные имена гарнитур, которые использует документ.
  2. 2. Дополнительный каталог передавайте через --font-path. В сборочной среде используйте тот же набор файлов шрифтов.
  3. 3. Во всех импортах пакетов оставьте точные версии. Обновление выполняйте отдельной задачей, а не одновременно с редактурой текста.
  4. 4. Данные CSV, JSON и библиографию храните рядом с исходниками либо получайте предсказуемым этапом до компиляции.
  5. 5. Для утверждённого выпуска сохраните исходники, список зависимостей, набор шрифтов и контрольный PDF.
  6. 6. При обновлении компилятора сравните страницы с формулами, таблицами, переносами, оглавлением и колонтитулами. Размер файла сам по себе не подтверждает одинаковый макет.

Шаг 4. Синхронизировать веб-проект через Git

  1. 1. В настройках аккаунта подключите GitHub или GitLab, затем откройте настройки конкретного проекта.
  2. 2. В разделе Version control свяжите проект с заранее созданным репозиторием или пустым каталогом репозитория.
  3. 3. Перед началом работы выполните pull и просмотрите изменения, пришедшие из удалённой истории.
  4. 4. После правки исходников нажмите push, введите содержательное сообщение коммита и отправьте изменения.
  5. 5. При изменении двоичного файла с двух сторон выберите нужную версию осознанно: изображения и другие бинарные ресурсы не объединяются как текст.
  6. 6. Синхронизация Git в веб-приложении остаётся экспериментальной; для выпуска сохраняйте обычную локальную историю репозитория и контрольный PDF.
Кнопки pull и push Git Sync в Typst
Кнопки pull и push показывают состояние Git Sync.
Screenshot © Typst GmbH, typst.app documentation
Панель синхронизируемой библиографии Typst с Zotero
Синхронизируемая библиография показывает время последнего обновления.
Screenshot © Typst GmbH, typst.app documentation
Расширенное файловое меню Typst с созданием манифеста и синхронизацией библиографии
Расширенное файловое меню объединяет служебные команды проекта.
Screenshot © Typst GmbH, typst.app documentation

Для конвейеров, где исходный материал приходит в другой разметке, полезно сопоставить подход Typst с Pandoc для конвертации документов и разметки. Pandoc умеет использовать Typst как один из PDF-движков, но сам по себе решает более широкую задачу преобразования форматов.

Экспорт, диагностика и финальная проверка

Финальная стадия — не просто нажатие кнопки загрузки. Экспорт определяет диапазон страниц, формат и PDF-профиль, а проверка подтверждает читаемость, ссылки, текстовый слой и воспроизводимость. Для серьёзного документа этот этап лучше выполнять по одному и тому же чек-листу.

Шаг 1. Настроить PDF и диапазон страниц

Меню Export & Preview в Typst с настройками PDF, PNG, SVG и HTML
Панель Export & Preview показывает диапазон страниц, версию PDF, профили PDF/A, PDF/UA и другие форматы.
Typst interface © Typst GmbH; screenshot source: Xeon Live
  1. 1. Откройте Export & Preview через File > Export as > PDF или стрелку рядом с быстрым экспортом.
  2. 2. Для полного документа оставьте All pages. Для проверки части выберите Current page или Custom ranges и задайте нужные номера.
  3. 3. Выберите версию PDF и дополнительный стандарт только по требованиям архива, издателя или процесса. По умолчанию Typst формирует PDF 1.7.
  4. 4. Не отключайте теги PDF без отдельной причины. По умолчанию Typst создаёт Tagged PDF как базу для доступности.
  5. 5. Скачайте файл и откройте его внешним просмотрщиком. Проверьте количество страниц, метаданные, поиск, копирование текста и внутренние переходы.

Шаг 2. Выбрать PNG, SVG или HTML вместо PDF

  1. 1. Для растрового изображения страницы выберите PNG. Проверьте разрешение, потому что оно напрямую влияет на детализацию и размер файла.
  2. 2. Для векторной страницы выберите SVG. Многостраничный документ экспортируется набором файлов, а не одним многостраничным SVG.
  3. 3. HTML в текущей линии Typst относится к экспериментальному направлению. В веб-приложении его предпросмотр включается в настройках проекта.
  4. 4. Для HTML отдельно проверьте шаблон, колонтитулы, абсолютное позиционирование и элементы, рассчитанные только на печатную страницу.
  5. 5. Не считайте совпадение PDF и HTML гарантированным. Семантическое содержание удобно держать общим, а оформление для paged и web разделять по цели.

Шаг 3. Найти и устранить типовые ошибки

  1. 1. При синтаксической ошибке сначала проверьте незакрытые круглые, квадратные и фигурные скобки, затем запятые между именованными параметрами.
  2. 2. При Unknown variable проверьте написание имени, область видимости и import. Функция, определённая внутри локального блока, снаружи недоступна.
  3. 3. При File not found проверьте регистр имени, расширение и относительный путь от файла, где выполняется обращение.
  4. 4. При предупреждении о шрифте выполните typst fonts и используйте точное имя семейства. Имя файла гарнитуры не обязано совпадать с её семейным именем.
  5. 5. При неизвестной ссылке проверьте метку объекта или идентификатор библиографической записи. Дубликаты меток устраняются переименованием одного объекта.
  6. 6. При переполнении страницы найдите конкретную широкую таблицу, неразрывную строку, картинку или контейнер. Глобальное уменьшение текста скрывает причину и ухудшает весь документ.

Шаг 4. Провести приёмку итогового PDF

  1. 1. Просмотрите весь документ в режиме целой страницы и отметьте пустые полосы, одиночные строки, неудачные разрывы и страницы с иной плотностью.
  2. 2. Повторите просмотр при масштабе 100 процентов. Проверьте резкость растров, толщину линий, мелкие подписи и математические индексы.
  3. 3. Перейдите по нескольким ссылкам из текста на формулы, рисунки и разделы. Номера должны совпадать с подписями.
  4. 4. Проверьте оглавление, библиографию, номера страниц, начало каждой главы и последние страницы приложений.
  5. 5. Выполните поиск по редкому слову, скопируйте абзац и формулу в текстовый редактор. Это выявляет проблемы текстового слоя.
  6. 6. Сохраните финальный PDF рядом с исходниками и данными выпуска. Следующую редакцию собирайте из тех же источников, а не правьте экспорт вручную.

Почему PDF собрался, но выглядит иначе у коллеги?

Проверьте версию компилятора, версии пакетов, входные данные и набор шрифтов. Различие гарнитуры меняет ширину строк и переносы страниц.

Почему комментарии не появились в PDF?

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

Почему изображение не находится?

Проверьте регистр имени, расширение и относительный путь от текущего файла. После перемещения ресурса обновите все обращения к нему.

Почему библиографическая ссылка остаётся неизвестной?

Проверьте запись в .bib или YAML, её идентификатор и наличие bibliography в собираемом документе. После исправления пересоберите проект.

Почему HTML отличается от PDF?

HTML-экспорт остаётся экспериментальным и использует другую модель представления. Печатные элементы и сложный абсолютный макет требуют отдельной проверки.

Почему готовый PDF нельзя исправить прямо в Typst?

Typst работает с исходной разметкой и пересобирает результат. Для объектной правки существующего PDF используется отдельный PDF-редактор.

Плюсы, минусы, альтернативы и практический выбор

Typst особенно силён там, где документ имеет структуру и должен воспроизводимо пересобираться: отчёты, статьи, дипломы, книги, спецификации, презентации и документы из данных. Его слабое место — задачи, где исходником уже служит чужой готовый PDF и требуется вручную двигать объекты, стирать текст или редактировать страницу без исходной разметки.

Что в Typst особенно полезно

Режим презентации 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 остаётся проверяемым выходным артефактом.

xeonlive.ru
Профиль автора на Sostav