Новости‎ > ‎

Начал перевод документации из markdown в gh-pages

Отправлено 3 янв. 2017 г., 1:04 пользователем Denis Baskovsky
GDS.io это удобный сервис поиска и бронирования по базе GDS (международной системы бронирования), отличающийся от аналогов простым и удобным JSON API. На данном этапе он уже поддерживает систему доверенных платежей, поиск и бронирование авиабилетов и заканчивает подключение отелей. Посмотрите сами - сервис однозначно выстрелит. 

Пока же я взялся за перевод его документации. Для формата хранения выбрал уже знакомый мне markdown (далее md). Пока переводил, столкнулся с некоторыми трудностями. 

Где хранить текст? 
На работе была похожая задачка, тогда решили хранить описание в одном файле. Это в итоге поставило крест на удобном добавлении фич - страничка долго загружалась, а изменения приходилось раскидывать по всему файлу. Решил проблему созданием отдельной директории docs и вынес файлы по контексту. 

Как генерировать html? 
До этого я использовал jsdoc с подключенным md-плагином, который генерирует симпатичную страничку вроде такой http://caolan.github.io/async/. К сожалению, как я не пытался настроить конфиг, мне не удалось заставить парсер склеивать несколько md-файлов. Побродив несколько часов по гитхабу я нашёл решение: markdown-folder-to-html. Он классно выполняет свою роль, и удобно стилизуется. Уже добавил подсветку синтаксиса highlightjs. Недостатки: нет поиска, неудобная панель навигации. Автор видимо забил на свою подделку, приходится допиливать своими силами. Уже закинул пулреквест с удалением ненужных md-файлов в выходящей директории.

Наконец, как автоматизировать процесс сборки? 
Хочется делать изменение сразу в веб-интерфейсе. Если всё норм - автоматически публиковать. Сразу оговорюсь, до конца этого пока не сделал, но как делать, в принципе, знаю. Тут мне должен помочь CI, нодовская библиотека gh-pages-deploy, и makefile с прокинутым гитовским ключиком для возможности пушить. Как сделаю, отпишусь. Следите за репой на гитхабе.


Работа над Qweeto постоянно перерождается, переименовывается, усложняется и это даже хорошо. Мир меняется, хочешь не хочешь, приходится приспособляться к этому. Идеи положенные ещё в универе претерпели кардинальные изменения. Главное, корень остался и он пока питает моё воображение.
Comments