H Git + book = GitBook в черновиках Tutorial

Приветствую всех Хабражителей!

Сегодня я хочу рассказать вам об одном инструменте, который мне очень, очень понравился. Если вы планируете создавать веб-версии ваших книг, документации и тому подобных вещей — этот инструмент достоин вашего внимания.

Предыстория

Давным-давно (кажется, в прошлом месяце) я рассказывал о своей книге. И многие из моих читателей пожелали видеть её в HTML-формате. Признаюсь, вначале я сопротивлялся этой идее, но потом, поразмыслив, понял, что веб-версия книги действительно была бы удобной. Сказано — сделано. Вот, собственно, и вся предыстория.

Как я хотел сделать вначале

Ну, думаю, создам отдельную страницу на сайте, скопирую туда текст, причешу его — и готово. К счастью, вовремя остановился… Как представил себе поддержание/согласование нескольких вариантов книги (HTML, PDF и электронно-читальные форматы) — так и стало мне нехорошо. Настолько нехорошо, что от такого сценария я отказался немедленно.

Как я хотел сделать потом

Уже третью неделю активно идёт перевод моей книги на великий и могучий Шекспировский, и вот в процессе работы над этим переводом я впервые услышал про формат Markdown. Кто не знает — это простой формат разметки текста (легче LaTeX). А вся вкуснота в том, что размеченный таким образом текст может быть сконвертирован в документы разных форматов, и в первую очередь в HTML. Кстати, на GitHub этот формат принят за основной.

Посмотрел я на этот Markdown — понравился: просто, лаконично. Кроме того, я услышал про утилиту pandoc, универсальный конвертор документов, умеющий, помимо всего прочего, превращать Markdown в HTML.

Ну, думаю, оно! Создал .md-файл, попробовал сконвертировать. В целом вышло аккуратно, но слишком примитивно. Да, можно было бы прикрутить свой CSS, но хотелось чего-нибудь готовенького. В общем, понял: нет, это не оно.

Как я сделал

Помог мне опять-таки один из моих читателей. В письме по поводу пожелания веб-версии книги он вскользь упомянул о GitBook. Я впервые слышал об этой штуковине (как выяснилось позже, этот проект очень молодой, существует менее двух недель), поэтому решил поглядеть. И вот что я увидел:

Write your books and courses using Markdown, GitBook will convert it to a complete static website.

Хм, подумал я, звучит вкусно. Ещё вкуснее стало, когда я увидел демонстрацию: gitbookio.github.io/javascript. Вот как это выглядит:



Очень приятный вид, удобство навигации, мобильная адаптация из коробки. И всё это делается одной-единственной командой из набора простых .md-файлов! Это именно то, что я искал. Собственно, об этом инструменте и пойдёт речь далее.

Устанавливаем

На главной странице GitBook сказано, что устанавливается утилита gitbook так:

$ npm install gitbook -g

Мне это ни о чём не сказало, поэтому начал искать. Первым делом я выяснил, что npm — это Node Packaged Modules. Признаюсь, это мне тоже мало о чём сказало, но господин Гугл привёл меня к Node.js. Как выяснилось, стоит установить себе эту Node.js, и npm автоматически установится вместе с ним. В общем, установил. Далее выполнил ту самую команду:

$ npm install gitbook -g

и gitbook был уже у меня.

Готовим репозиторий

Прежде чем строить веб-книгу, необходимо подготовить для неё дом. Ну а раз сама книга будет жить на GitHub, домом для веб-версии станет GitHub-страница. Кто не в курсе — GitHub предлагает своим пользователям бесплатный сервис для создания сайтов, крепко связанных с их репозиториями. Вот суть этого сервиса:

Websites for you and your projects. Hosted directly from your GitHub repository. Just edit, push, and your changes are live.

Пустой репозиторий для книги у меня уже был, так что осталось лишь настроить его. Настройка оказалась предельно простой: необходимо создать в репозитории пустую ветку по имени gh-pages, что-то в неё положить, закоммитить-запушить — и вот уже нас встречает ваша GitHub-страница. Однако, как выяснилось, делать всё это следует в точности как описано здесь. В общем, сделал — и веб-страница уже тут: denisshevchenko.github.io/ohaskell/index.html. Обращаю ваше внимание: после первого пуша в ветку gh-pages страница становится доступной не мгновенно, а через несколько минут.

Строим веб-книгу

Итак, исходное сырьё — это .md-файлы. Синтаксис Markdown-формата описывать не стану, ибо раз и два. Обрадовался я и, сломя голову, ринулся в бой: радостно создав .md-варианты первых четырёх вступительных глав, кинул их в каталог, попробовал собрать — и разумеется, ничего не получилось. Как выяснилось, нельзя скормить утилите gitbook кучу .md-файлов. Необходима структура. Поэтому в ветке master я создал следующее:

README.md    # Титульный лист книги
SUMMARY.md   # Описание структуры книги
intro/
    README.md   # Введение к вступительной части книги
    for-whom.md
    what-for.md
    who.md
    why.md

Идея именно такая: в ветке master будет лежать Markdown-версия книги, а в ветке gh-pages — веб-версия. Обращаю ваше внимание: файлы README.md и SUMMARY.md необходимы. В первом из них пишем некое общее введение, которое станет титульной веб-страницей книги. А вот в SUMMARY.md необходимо описать структуру книги. В моём случае это выглядит так:

### Summary

* [Лирическое вступление](intro/README.md)
  * [Кто](intro/who.md)
  * [Почему](intro/why.md)
  * [Зачем](intro/what-for.md)
  * [Для кого](intro/for-whom.md)

Я отразил иерархию страниц в стиле классического Markdown-оглавления. Разумеется, файлы, не указанные в SUMMARY.md, частью веб-книги не станут.

Строим

Настало время строительства:

$ gitbook build ./ --github=denisshevchenko/ohaskell --title="О Haskell по-человечески"
Starting build ...
Successfuly built !

Готово. Кстати, обращаю ваше внимание на параметр --github=denisshevchenko/ohaskell. Здесь denisshevchenko — имя моего профиля на GitHub, а ohaskell — имя репозитория.

В итоге в корне репозитория появилась папка _book, а в ней — о чудо! — лежал готовый сайтик:

_book/
    README.html   # Титульный лист книги
    SUMMARY.md
    gitbook/
        app.js
        fonts/
        images/
        jsrepl/
        index.html   # Стартовая страница сайта
        intro/   # Сгенерированные страницы первой части книги
            README.html
            for-whom.html
            what-for.html
            who.html
            why.html

Коммитим это хозяйство и пушим в ветку master.

Новоселье

Настало время поселить веб-книгу в её уютный дом:

$ git checkout gh-pages
$ git checkout master -- _book
$ git mv _book/* .

Первой командой переходим в ветку gh-pages. Второй командой забираем из ветки master тот самый каталог _book, созданный gitbook-ом. Третьей командой вытаскиваем содержимое этого каталога в корень ветки gh-pages. К сожалению, я так и не выяснил, как забрать из другой ветки лишь содержимое каталога, а не весь каталог. Завершаем:

$ git add .
$ git commit -a -m "FIrst init for real book."
$ git push origin gh-pages

It works!

Вот, собственно, и всё. Идём по адресу denisshevchenko.github.io/ohaskell/index.html — и вот она:



Обращаю внимание на автоматически создаваемые ссылки вверху страницы: ведут на страницу автора репозитория, на сам репозиторий, ну и социальные ссылки, куда ж без них-то.

Шероховатость

Единственная шероховатость — английские названия в именах ссылок и на больших зелёных кнопках перехода. Всё-таки если книга на русском, хочется видеть на русском всё. Очевидно, можно как-то влезть в исходники gitbook-а и поправить. Нужно будет изучить этот вопрос.

Вот и всё, друзья. На мой взгляд, GitBook заслуживает пристального внимания. Определённо, у этого инструмента есть будущее.