Перевести tlroadmap в честный веб #257
Description
tlroadmap -> https://tlroadmap.io
Кажется, пришло время оформить наполовину сделаную работу в виде полноценного ишью.
Зачем tlroadmap уезжать в веб?
tlroadmap из небольшого .mm файла и набора статей превратился в базу знаний, которая усложнялась и будет постепенно усложняться дальше: генерация артефактов, проверки, шаблонные файлы, перекрёстные связи, переводы, глоссарий, ...
При этом пользоваться им становится всё сложнее с обоих сторон: читателю приходится качать файл / перебирать репозиторий, а писателю разбираться с флоу, проверками и решать конфликты между разными версиями бинарных артефактов.
Какое решение?
Сейчас источником истины для дерева компетенций служит .puml файл с ссылками на .mm файлы, которые лежат в достаточно плоской структуре директорий. Из этого .puml-файла генерируются связанные артефакты: .png, .svg, .mm, часть .md и кладутся в репозиторий.
Что я предлагаю:
- Источником истины считать структуру папок и .md файлы в ней.
- Мета-информацию (тайтл, теги, цвет ветки, расположение ветки, ...) хранить в .md файлах в frontmatter-формате или любом другом
- Чтобы поддерживать i18n каждая ветка содержит ru.md, en.md, %anylocale%.md файл
- Утилита при сборке извлекает дерево и нужные мета-данные из файлов и структуре папок и кладёт его в какой-нибудь структурированный формат (json, yaml)
- Утилита генерирует артефакты дерева (картинки, .mm файлы, т.д.)
- Утилита генерирует статический сайт
Например из такой структуры файлов:
Должен генерироваться сайт с такой структурой:
Что нужно предусмотреть:
- Минимальную боль для писателя (контрибьютора) — в идеальном случае единственное, с чем он должен работать — это с редактором .md файла.
- Генерация должна быть лёгковесной и быстрой: чтобы иметь возможность разворачивать тестовые окружения под каждое изменение
- Генератор статического сайта должен быть достаточно мощным и расширяемым, чтобы иметь возможность быстро добавлять интерактивные компоненты
- Сгенерированный статический сайт должен иметь удобную мобильную версию, быть быстрым (PageSpeed > 65), поддерживать кеширование
- Сгенерированный статический сайт должен быть SEO-friendly: иметь статичную meta-информацию, возможность настроить её для каждой страницы
- Сайт должен трекать перемещение пользователя по страницам, строить статистику
- Возможность интеграции с сервисами по менеджементу переводов (crowdin, gitlocalize)
Какие технические детали?
Я и @teners реализовали большую часть из озвученных выше штук, использовав следующую магию:
- Мы распихали весь текущий родмап по вложенным папкам и назвали их
ru.md - В "ветки", у которых нет описания мы добавили мета-информацию с переводом заголовка
- Мы сгенерировали из этой структуры статический сайт на VuePress
- Мы сгенерировали из этой структуры .json дерево специальным vuepress-плагином
- Мы добились красивых URL-ов другим специальным vuepress-плагином
- Мы вывели всю генерацию артефактов в Github Actions, и прикрутили автодеплой в netlify с ревью-окружениями для каждого PR
Есть и подводные камни:
- Репозиторий tlroadmap — база знаний, а не ПО. Лицензия CC-BY-SA 4.0 плохо подходит для свободного ПО, и с этим есть очевидные проблемы. Весь код мы максимально вынесли за пределы репозитория под MIT-лицензиями, и это нужно будет продолжать делать.
- Мы взяли VuePress в качестве генератора и сейчас достаточно сильно от него зависим, написали специальные плагины, подкрутили всё что можно подкрутить и будем продолжать подкручивать. Весь интерактив, кастомные компоненты, SEO-магия и другие штуки часто будут зависеть от Vue как фреймворка. Впрочем, такую структуру файлов легко съест любой другой генератор статических файлов (Hugo, Jekyll, Gatsby), поэтому переезд возможен в любой момент.
Что теперь?
Когда все из обязательных условий будут выполнены форк b0g3r/tlroadmap будет влит в tlbootcamp/tlroadmap, и структура файлов в репозитории изменится.
Скорее всего вместе с этим сломаются все текущие PR :(
Чтобы отслеживать будущие ишью по сайту предлагаю создать лейбл website, и перенести оставшиеся в форке ишью в апстрим.
После завершения работы над базовой функциональностью я предлагаю пустить зов по чатикам на лучший компонент для интерактивного отображения родмапа на сайте.