Thread by @andrey_sitnik

Первая версия сайта с документацией @logux_io готова. Проверйте:
logux.io

Само собой сайт построен не на популярных реакт-решениях. В треде расскажу об экспериментах, которые удалось в нём реализовать.
github.com/logux/logux.io

@logux_io В сайтах с документацией обычно мало работы с DOM — поэтому нам не нужна библиотека автоматического изменения DOM. Нет смысла использовать Реакт (и Gatsby), Vue.js, Preact или Svelte.

Вот весь JS-код сайт (меньше, чем многие даже микро-библиотеки).

@logux_io Метрики logux.io в Google Lighthouse.

Ещё при разработке я смотрел на observatory.mozilla.org, который проверяет настройку безопасности (XSS не так опасен для статичного сайта, но хорошие практики лучше ввести в привычку).

@logux_io За логотип @logux_io спасибо @antiflasher и шрифту Курбанистика от instagram.com/mishapriem/

Дизайн делала @egodyston — очень профессионально, было приятно работать. Она круто проработала и тёмную и светлу тему при постоянной заботе о сильном контрасте.

https://twitter.com/eritramal/status/1202577930121023488

@logux_io @antiflasher @egodyston Как обеспечить хороший DX разработки статического сайта без Gatsby? Мы для этого берём Parcel.

Подаём на вход pug-шаблон
github.com/logux/logux.io…

Держим компоненты изолированными по БЭМ
github.com/logux/logux.io…

В отличии от Вебпака всё работает из коробки
github.com/logux/logux.io…

@logux_io @antiflasher @egodyston Пример относительно сложного компонента:

CSS изолирован через префиксы с именем класса (но для такого простого проекта можно использовать теги, если в компонент нельзя вкладывать другие компоненты)
github.com/logux/logux.io…

Вёрстка вынесена в pug-примесь
github.com/logux/logux.io…

@logux_io @antiflasher @egodyston JS-код компонента тоже изолирован. Он ищет классы компонента в вёрстке и оживляет их (если ничего нет, то не работает)
github.com/logux/logux.io…

@logux_io @antiflasher @egodyston Даже для простого сайта документации у нас есть UI-кит.

logux.io/uikit/

Если я находил какой-то баг, то старался добавить его в UI-кит. Для меня UI-кит — как тестирование, а не просто каталог базовых компонентов. Глянут на него должно быть понятно, что нет регрессий.

@logux_io @antiflasher @egodyston Parcel собирает именно UI-кит. Страницы их JSDoc и Маркдауна генерируют отдельный скрипты. Я подумал, что так будет проще, чем пытаться сохранить hot reload для разработки остальных страниц. Всё равно документация и API собирается из других репозиториев.
github.com/logux/logux.io…

@logux_io @antiflasher @egodyston Вот скрипт сборки сайта. Туда же вынесены оптимизации продакшен-версии
github.com/logux/logux.io…

Каждый шаг вынесем в отдельный файл и получилось элегнатно построить дерево задач на основе async/await
github.com/logux/logux.io…

@logux_io @antiflasher @egodyston Вау, круто видеть контрибьютора в Parcel. Спасибо. Использую pug и Parcel уже в проектах 5-10.

А проседание кнопок при клике — это специально заложенный фидбэк на клик.

https://twitter.com/xxxTy3uKxxx/status/1202585893019770881

@logux_io @antiflasher @egodyston Сами маркдаун-файлы у нас лежат в отдельном репо
github.com/logux/docs

На первый шаг сборки мы скачивает их и все репозитории библиотек, чтобы отпарсить JSDoc.
github.com/logux/logux.io…

Скачивание и разархивация идёт через воркер, чтобы было быстрее
github.com/logux/logux.io…

@logux_io @antiflasher @egodyston Сборка сайта идёт через Parcel, потом Rollup досжимает JS-файлы.

А вот с Маркдаун и JSDoc хитрее. Я использую unified.js — универсальный AST (а-ля PostCSS) для Маркдауна, HTML и даже грамматики текста.
github.com/unifiedjs/unif…

Remark парсит md в AST. Documentation парсит JSDoc.

@logux_io @antiflasher @egodyston Из-за универсального AST unified.js можно применить какие-то фильтры на md AST (например, добавить yarn примеры ко всем примерам с npm)
github.com/logux/logux.io…

Потом сконвертировать md AST в HTML AST и применить фильтры уже там (общие для HTML AST от Documentation.js)

@logux_io @antiflasher @egodyston Деплой идёт через GitHub Actions
github.com/logux/logux.io…

После сборки HTML, собирается докер-образ с nginx
github.com/logux/logux.io…

И запускатся в Google Cloud Run. Перед Run стоит Cloudflare с кешированием HTML. За счёт HTTP/2 и 3, Brotli и TSL 1.3 0-RTT всё просто летает.

@logux_io @antiflasher @egodyston Задавайте свои вопросы по сборке и деплою, а мы пока переходим к дизайну и инструментам организации сообщества

@logux_io @antiflasher @egodyston Вместо популярного Slack, для общения и вопросов мы используем @gitchat.

У Gitter есть крутой Sidecar, когда чат интегрируется в сайт проекта и задать вопрос можно нажав лишь 2 кнопки и гитхаб-авторизацию. Сравните с инвайтами в Slack и отдельным паролем в менеджере паролей.

@logux_io @antiflasher @egodyston @gitchat Вторая особенность UX сайт — отказ от двойного вертикального и горизонтального меню и переход на общее двухуровневое.

В итоге в главное меню можно добавить больше пунктов и раскрыть проект чисто пунктами меню. Сразу видно для какие языков есть API, что есть стандандарт протокола

@logux_io @antiflasher @egodyston @gitchat Обратите внимание, как сочно @egodyston сделала меню для телефонов и узких планшетов (уже чем iPad, на iPad десктопная раскладка).

А на десктопе по наведению шрифт в меню меняется на фирменную Курбанистику.

@logux_io @antiflasher @egodyston @gitchat Чтобы показать, что чат живой и там ответят на ваш вопрос (не бойтесь спрашивать, я обычно отвечаю в течении суток максимум) — мы показывает живое кол-во пользователей чата.

Обновляется этим скриптом при деплое
github.com/logux/logux.io…

@logux_io @antiflasher @egodyston @gitchat Другая особенность сайта — мы не делает отдельных страниц для разных технологий. Вместо этого мы для примеров кода делаем переключатель. Если вы выбрали Node.js один раз, то мы запомним и дальше будет показывать советы именно для этого языка.

@logux_io @antiflasher @egodyston @gitchat Само собой уделили внимание доступности.
1. Везде есть яркие фокус-стили.
2. Клавиатурная навигация продумана даже нестандартных элементов типа этого переключателя языков.
github.com/logux/logux.io…
3. Есть невидимая Skip navigation для програм чтения экрана

@logux_io @antiflasher @egodyston @gitchat Для работы в офлайн logux.io ставит сервис-воркер, который кеширует весь сайт
github.com/logux/logux.io…

Но кеш на мобилке или при navigator.connection.saveData кеш создаётся только при установки сайта как приложения на рабочий стол
github.com/logux/logux.io…

@logux_io @antiflasher @egodyston @gitchat После установки сервис-воркер загружает все файлы сайта
github.com/logux/logux.io…

Список файлов в код вставляет сборка
github.com/logux/logux.io…

Потом сервис-воркер перехватывает все HTTP-запросы и отдаёт версию из кеша
github.com/logux/logux.io…

@logux_io @antiflasher @egodyston @gitchat В сервис-воркере в именах ассетах стоит хеши от их содержимого. Таких хешей нет у имён HTML-файлов поэтому в файл сервис-воркера так же записывается хеш от HTML-файлов.

Меняется файл → меняется код сервис-воркера → когда браузер его обновит, он удалит обновит файлы в кеше

@logux_io @antiflasher @egodyston @gitchat Сервис-воркер с кешированием всех файлов очень сильно ускоряет переход между страницами. В Хроме он вообще выглядит мгновенно (70-80 мс).

В итоге пока решил не делать PJAX-навигацию (когда JS меняет body на новую страницу). Хотя она изначально планировалась.

@logux_io @antiflasher @egodyston @gitchat И последняя мелкая деталь заботы о пользователях. У нас свой подсветка синтаксиса для ini, bash и diff.

Подсветка bash отделяет программу, популярные команды и аргументы.

А подсветка diff позволяет скопировать код без копироания + и −.

github.com/logux/logux.io…

Через пару часов буду переводить этот тред на английский в @sitnikcode. Что в нём исправить и уточнить?

@sitnikcode Кстати, да. Для локального запуска образа, я использую podman вместо Docker.

Podman не требует для запуска сервера с root-доступом. Собранные контейнеры хранятся в home-директории пользователя. И его CLI API полностью совместимо с docker CLI.

https://twitter.com/exdeniz/status/1202617839259148288

@sitnikcode Кастомный скролл — дейстивительно плохо.

Но на logux.io нативный, просто кастомизированный через CSS. Фаерфокс, Хром и Сафари позволяют менять цвет и ширину скролла.
github.com/logux/logux.io…

https://twitter.com/CyberAP/status/1202723625931018240

@sitnikcode По совету @dark_mefody добавил touch-action: manipulation в CSS и logux.io стал работать «быстрее» в мобильном браузере.
github.com/logux/logux.io…

Или почему важно читать трансляции с конференций.

https://twitter.com/webstandards_up/status/1203234255087779840

@sitnikcode @dark_mefody В дизайне logux.io у ссылок прибитое 0.5px подчёркивание.

В Фаерфоксе есть text-underline-offset и text-decoration-thickness.

Для остальных браузеров — background с Custom Properties фона. Отделить браузеры можно через выражение supports.
github.com/logux/logux.io…