Максим, а можно я это прямо в канал репостну?

Я перетащил нашу документацию с самописной обертки вокруг ruby markdown на foliant.

Почему вообще возник вопрос о перезде?

* код писал я, причем очень давно и никакого желания дальше его развивать не было
* то, как я генерировал PDF с помощью ruby prawn было мягко говоря по-спартански

По сравнению с mkdocs и прочими фолиант подкупил интеграцией с пандоком, очень важная штука: бесплатно из коробки top-level поддержка PDF.

Чего мне не хватало из коробки в фолианте?

1. переименовывания результирующих файлов из их понятных имен вида live/publish.md в ужасный SEO-транслит potokovaya-peredacha/publikaciya
2. редиректов с человеческих unix-имен на транслит
3. возможности понять, какой урл будет у этой же страницы на другом языке для иконки языка
4. выгрузка кусков конфига из английской документации на диск для автотестов (мы тестируем документацию) и вставка их в русский вариант
5. выгрузка кусков документации в json для вставки их в админку нашего продукта


В целом всё это получилось решить плагинами, один из которых к mkdocs.

С чем возникли проблемы:

1. рубийный маркдаун существенно вольготнее относится к верске, чем питонячий. Пришлось много текста править
2. после рубийной Nokogiri, парсить HTML регекспами в питоне очень грустно. Очень не хватает API по объектному доступу к AST markdown
3. есть некоторая путаница между слоями метаданных фолианта и mkdocs. Вообще хотелось бы чтобы это не было разными вещами
4. процессоры фолианта разрешают падать и идти дальше. Реалии авторов фолианта такие, что им важнее собрать хоть что-то, чем собрать всё корректно. Мне наоборот — ворнинг уже повод упасть и не собирать документацию.
5. Пришлось написать немало кода, который подправлял плохую верстку в наших 3 миллионах символов (280 тыс слов)


Чего отдельно понравилось:

1. глобальное пространство имен анкоров. Ссылаться на уникальное по проекту имя секции — бесценно.
2. упаковка картинок и прочих ассетов в webpack-стиле, это важно
3. ну и вообще то, что люди решили его опенсорснуть и довести до отчуждаемого состояния. Это круто.

У нас ТЗ Foliant'ом собирается, если конкретно

Спасибо за отзыв! Историю с падением пайплайнов мы доработаем, да. А что касается правки AST, учитывая, что внутри пандок, можно подумать в сторону пандочных фильтров.

Не думал Imagineui в препроцессор для Фолианта завернуть? Он бы пригодился :)

А для таргета MkDocs отдельно решение пилить?

Мне кажется, сейчас Foliant решает своей фишкой про single-source publishing с минимальными усилиями

Соответственно, не хотелось бы таргето-зависимые допилки наворачивать в своих проектах

Ну, это зависит от того, что ещё с AST делать, конечно. Если форматоспецифичные вещи, то да, для всех таргетов, к сожалению.

Я б очень хотел уметь смещать уровень заголовков при инклюде .md, например

Не, такой опции нет. И после 5-го уровня проблемы при сборке могут быть, мы тут не подменяем их, насколько я помню. Надо тут докрутить по-хорошему, не сложно вроде бы

Ох, это вообще не про процесс разработки...

Или что ты имеешь ввиду?

Я имею в виду, что функции, вроде "свиднуть заголовки", "отрезать после 5 уровня глубины", можно переделать через какую-то общую либу для препроцессоров