stepanzh

Markdown + pandoc

Вероятно, вы впервые столкнулись с TeX-ом, когда увидели текст со вставками из уравнений, как ниже.

**Эквивалeнтность массы и энергии** — физическая концепция теории относительности,
согласно которой полная энергия физического объекта (физической системы, тела)
в состоянии покоя выражается через его массу и скорость света

$$
E = m c^2
$$

где $E$ — энергия объекта, $m$ — его масса и $c$ — скорость света в вакууме.

Это его величество Markdown, простейший язык разметки. Он столь прост и удобен, что встречается повсюду. Но Markdown здесь не обычный, а с расширением для набора уравнений. Если нужно написать уравнение в отдельной строке, то оно заключается в $$ ... $$, а если в той же строке, то в $ ... $. А вот синтаксис набора уравнений тот же, что в TeX-е. Так веб-мир признал лучший способ набора уравнений 😎

Чтобы превратить Markdown-файлик (тупа текст) в нормально выглядящее нечто, требуется конвертер. Можно фигануть всё в html, а там браузер отрисует текст, заголовки и уравнения (MathJax или KaTeX). Но нам нужна человеческая pdf-ка, ведь держать конспекты в html как-то не комильфо.

Существует титан конвертации и имя ему pandoc. Он умеет конвертировать что угодно во что угодно. Pandoc настраиваем: в нём можно создать свой шаблон для конспекта, который потом можно дёргать одной командой для конвертации. То есть, вы пишите в Markdown-е (это контент), а pandoc его фиганёт в TeX, вставит в шаблон, запихнёт всё в компилятор типа pdflatex и даст вам pdf-ку.

Способ кажется удобным, но есть подводные камни.

• Приходится разбираться с настройками pandoc-а и его синтаксисом для шаблонов.
• Теряется возможность кросс-ссылок на уравнения и составления списка литературы. Вроде ок для коротких заметок, но для конспекта книги уже не то.
• Появляется с десяток временных файлов, которые нужно знать, как быстро удалить и не мусорить.
• Большой пайплайн технологий растёт, и в каждом этапе свои ограничения.

По итогу, я отказался от такой связки. Её нелегко настраивать, нелегко чинить, а часть инструментов вёрстки отсутствует.

Obsidian

Obsidian топ. И в нём можно спокойно работать с заметками, но не с конспектами. Поначалу привлекает, что можно держать базу знаний и конспекты в одном месте, а ещё и WYSIWYG 🍑

Но минусы критичны.

• Кривая система кросс-ссылок внутри одного документа.
• Под капотом Markdown с расширениями, который не дотягивает до функционала TeX-а. Даже для набора уравнений.
• Фиг вы там напишите лонгрид с уравнениями на 5+ экранов. Obsidian просто начнёт тормозить.

Typora

Самое привлекательное в Obsidian — WYSIWYG редактор. Пишешь и сразу видишь, что получается. Короче, Word для программистов.

Исторически, до Obsidian, я пользовался Typora. Это Markdown редактор. Жутко красивый Markdown редактор. У него тот же минус, что и у Obsidian — медленная работа с большими конспектами. А ещё он платным стал после беты... 👋

Полагаю, что и другие Markdown редакторы постигает та же участь. Интересно, будут ли они быстрее работать, если переедут на рендер уравнений в KaTeX?..

Typst

Typst, Typst, Typst... Когда я намучался с pandoc-ом и Markdown-редакторами, то увидел его. Казалось, что нашлись люди с теми же проблемами, которые нафигачили свой язык и выкатили быстрый компилятор (его можно скачать с репозитория проекта).

Тут есть всё: кросс-ссылки, список литературы, уравнения, вставки кода с подсветкой, настройка стилей. Компилятор это малюсенький бинарник, которого кормишь корневым файлом, а получаешь pdf-ку. Есть watch-режим — редактируешь файлик, а pdf-ка сама обновляется. Позже и экосистему пакетов создали. Ну конфета же 🍬

Однако, мой опыт с Typst оказался токсичным. Я застал его на сырой стадии, API было нестабильным, и мне пришлось часть заметок править с обновлением компилятора. Пакетная база (тогда) была сырой, а история с Typst напоминала тренд «перепишём всё на Rust».

Тем не менее, я всё ещё слежу за Typst, вроде бы проект движется в правильном направлении. Вернусь, чтобы опробовать снова, но не раньше версии 1.0.

Моя история с Typst научила следующему — не столь важен язык или компилятор, сколь экосистема.

Поэтому с TeX-ом ему ещё предстоит потягаться. Typst активно поддерживают в сторонних проектах, например, его добавили в pandoc и некоторые SSG. Это хороший знак для Typst, и я верю, что он однажды займёт свою нишу, потеснив TeX.

Ваш опыт с Typst может быть другим, более позитивным. Поэтому, я бы рекомендовал его попробовать, но с опаской. Будьте готовы однажды написать велосипед (не осуждаю, кому-то это в кайф).

Что в итоге по альтернативам?

Я считаю, что для коротких заметок хватает Markdown-редактора с поддержкой уравнений. Это удобно за невысокую плату — отсутствие некоторых возможностей TeX-а по набору уравнений и лаги на больших документах.

Если у вас есть время на раскачку, попробуйте Typst. Можно ещё и в опенсурс законтрибьютить — строчка в CV.

Если вам нужно фигачить серьёзные конспекты, например, семестровый курс по матану, то в 2025-ом выбирайте TeX. А я вам покажу, как упростить с ним работу донельзя.

Итак...

Дистрибутив

Когда пытаешься разобраться с TeX-ом, то встречаешь зоопарк из терминов и технологий (о нём бонус в конце). Это отталкивает, вкатиться тяжело, минус вайб. Решением здесь являются дистрибутивы (TeX installation). Дистрибутив это набор всего для работы с TeX-ом, включая

• компиляторы,
• latexmk (о нём позже),
• и графический менеджер пакетов, чтобы не возиться с консолью.

Я не парюсь и качаю полную версию дистрибутива TeX Live. Он популярный и обновляется раз в год (вроде). У меня с ним не бывало проблем. Один лишь недостаток — полная версия весит несколько гигов. Есть облегчённые версии, но потом приходится по логам с ошибками гуглить, чего не хватает.

При установке дистрибутива обычно требуется указать реестр «откуда качать». В мире TeX-а это называется CTAN. Их много, выбирайте тот, что географически поближе.

В целом, установка сводится к нескольким кликам или паре строчек в консоли.

Компиляторы

Я использую два компилятора: pdflatex (он же pdfTeX) и xelatex. Они оба выдают pdf-ку, но первый я использую для документов на английском языке, а второй для работы с документами на кириллице.

У них отличаются подключения шрифтов и проставление языков документа, но это легко гуглится. Контент же оформляется одинаково.

Ещё я рассматривал LuaTeX, но меня оттолкнули предупреждения о сыроватости (на 2024 год), а главная фича — программирование на Lua вместо TeX-а мне не нужна. Ещё для luatex есть какие-то уникальные пакеты, мне пофиг.

latexmk

До того, как я узнал о latexmk, мой процесс работы с TeX-ом выглядел примерно так.

1. Ищу команды для компиляции и прописываю их в Makefile.
2. Редактирую исходники и зову make.
3. Добавляю фичу X в документ.
4. Компиляция ломается, перейти на шаг 1.

И так несколько итераций, по одной на фичу: для кроссылок, библиографии и, например, генерации содержания. Это больно: нужно знать не только порядок команд, но и сколько раз их вызывать. Оказывается, TeX так устроен: иногда нужно вызвать одну и ту же команду 2-4 раза, чтобы всё собралось 🤯

В какой-то момент компиляция ломается насовсем, и всё сводится к make clean main.pdf. Т.е. документ после любой правки пересобирается с нуля, что долго и неправильно.

Так вот оказывается, для TeX-а есть система сборки latexmk, и она уже включена в дистрибутив. С ней 99% документов компилируются одной командой.

latexmk -pdf main.tex

У latexmk есть суперская фича — можно редактировать документ и получать обновлённую pdf-ку на лету. Делается это так.

latexmk -pdf -pvc main.tex

Это тот самый экспириенс, который даёт Overleaf.

Я использую всего несколько команд.

latexmk -pdf -pvc main.tex
latexmk -pdfxe -pvc main.tex
latexmk -c

Первые две для компиляции на лету в pdflatex или xelatex, а последняя для удаления большинства вспомогательных теховских файлов (auxiliary).

neovim

Я использую neovim, когда могу. А для работы с TeX-ом в использую две вещи.

• Сниппеты
• Плагин vimtex

Систему сниппетов я перенял у Гила Кастеля (Gill Castel): здесь код, а здесь как это работает. У Гила есть простые и сложные сниппеты, я брал только простые и дополнил их своими, мой конфиг тут. Ниже пара гифок, чтобы понять, как это выглядит.

Круто, да? Можно на лету набирать всякое, не отвлекаясь на скобки и бэкслэш.

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

Как-то ещё я neovim не настраиваю. Не люблю превращать его в IDE.

Классы

При создании документа TeX обязывает выбрать шаблон оформления: статья, книга, CV и т.п. Этот шаблон называется классом. Мне хватает двух.

• article — для заметок, коротких документов (скажем, до 20 страниц)
• memoir — для конспектов и просто длинных документов

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

И решение есть — создание своего класса. Классно то, что можно не создавать класс с нуля, а лишь наследоваться от существующего и импортировать список пакетов. В общем, можно сделать всё, что происходит в преамбуле документа.

Как их делать, можно почитать в статье Overleaf — Writing your own class. А ниже кусочек класса для заметок А4, которые я выкладывал в телеграмм-канале.

%
% Стандартная штука
%
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{stepanzha4note}[2024-10-20 A4 note of Stepan Zakharov]

%
% Базируемся (наследуемся) от article
%
\LoadClass[12pt]{article}

%
% Используем Helvetica для xelatex
%
\RequirePackage{fontspec}
\defaultfontfeatures{Mapping=tex-text}  % So TeX's --- become font's longdash.
\setmainfont{Helvetica}
\newfontfamily{\cyrillicfont}{Helvetica}

%
% Проставляем языки документа
%
\RequirePackage{polyglossia}
\setdefaultlanguage{russian}
\setotherlanguages{english}

...

%
% Часто используемые пакеты
%
\RequirePackage{amsmath}
\RequirePackage{booktabs}
\RequirePackage{csquotes}
\RequirePackage{xcolor}
\RequirePackage[
  implicit=false,
  urlbordercolor=blue,
]{hyperref}
\urlstyle{same}

...

Логика простая: то что, происходит в преамбуле документа, в классе происходит так.

\documentclass[...]{...} → \LoadClass[...]{...}
\usepackage{...}         → \RequirePackage{...}

Все остальное как в обычной преамбуле документа. Когда я делал первый класс, просто переносил по одной команде из преамбулы в класс и компилировал.

Практические штуки

🔖 Когда я конспектирую, то оставляю ссылку на место в источнике (например, номер уравнения в оригинале).

\newcommand[1]{\citesrc}{\cite[#1]{Nocedal2004}}

...

\citesrc{eq.~3.30}

🔖 Я обычно забиваю на нарративное повествование и злоупотребляю remark, theorem, proposition и т.п (см. Overleaf — Theorems and proofs). Грубо говоря, это то, что я бы подчеркнул в книге плюс заметки на полях.

🔖 Мой идеальный процесс конспекта книги такой.

1. Выбрать главы, которые я хочу понять.
2. Определить, какие главы мне нужно прочесть/пролистать, чтобы понять целевые главы.
3. Определить порядок чтения.
4. Следовать порядку чтения и трекать прогресс прям в конспекте.

🔖 .gitignore для теха

🔖 Моя типичная файловая структура с конспектом.

content/
  ch-01-foo.tex
  ch-02-bar.tex
  ...
main.tex
bib.bib 🚗

🔖 Bib файлы заполняю вручную, в алфавитном порядке по фамилии первого автора. И оставляю «книжные полки» с алфавитом — это упрощает поиск.

% Aa
% Bb

⋮

% Yy
% Zz

🔖 В TeX-е можно рисовать. Например, с помощью tkiz. Я пробовал, и это неудобно плюс приходится учить ещё один язык. Рисовать мне удобнее в Inkscape. Он умеет экспортировать документ так, чтобы TeX смог отрендерить все уравнения на картинке. А ещё экспорт можно автоматизировать. Подробнее в ещё одном крутом посте Гила и этом мануале.

Что такое TeX?

TeX это система вёрстки, созданная тем самым Дональдом Кнутом и опубликованная аж в 1978-ом. Эта система состоит из набора тулзов, которые позволяют создавать в цифре документы высокого качества, не уступающие типографии.

TeX позволяет набирать команды для позицирования любой закорючки в любом месте страницы. Из закорючек можно складывать, например, буквы и цифры, а их объединять в шрифты.

Кроме того, TeX расставляет символы в строки, абзацы и страницы. Сам. Это супер-гуд.

На выходе TeX даёт dvi-файлик, который можно распечатать или посмотреть на мониторе (т.е. виртуально распечатать 🤓). DVI значит device independent, то есть кроссплатформенный, включая и компьютеры, и принтеры.

Итак, TeX это оригинальная система: в ней свой язык вёрстки, свой компилятор и свои форматы файлов. Она так продумана, что жива до сих пор. Кнут голова!

Что такое LaTeX?

Проблема TeX-а в том, что язык вёрстки в нём слишком низкоуровневый. Однако, язык позволяет объединять несколько простых команд в сложные, называемые макросами. Тут появляется LaTeX.

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

LaTeX был удачно продуман и им пользуются большинство людей из мира теха.

Что такое TeX engine?

TeX engine это компилятор. Он питается TeX-файлами, и даёт на выходе что-то, что можно посмотреть или распечатать. В случае оригинального TeX-а на выходе dvi файл.

Компиляторы есть разные, но популярных сейчас всего три: pdflatex (pdfTeX), XeLaTeX и LuaTeX. Все они превращают исходники в pdf-ку. Но есть отличия в том, что они умеют.

Что такое TeX installation?

Ещё один смущающий термин, но за ним скрывается дистрибутив, тулкит. Так вот TeX installation это коллекция всего необходимого, чтобы начать техать.

В наборе вы можете ожидать компиляторы, пакеты типа amsmath, шаблоны документов и даже IDE.

А где искать документацию?

Overleaf хороший источник, оттуда можно узнать базу. Ещё гуглёж проблемы часто приводит на LaTeX stack exchange, там норм. Ну а документацию к любому установленному пакету можно получить утилитой texdoc.

$ texdoc amsmath

На этом у меня всё.