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 — и вот она:



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

Не только English

На данный момент разработка GitBook ведётся семимильными шагами, и буквально на днях была добавлена одна очень полезная возможность. Речь идёт о многоязычных книгах, а поскольку моя книга как раз и пишется на двух языках, я не мог пройти мимо такой фичи. Делает всё предельно просто.

Создаю в корне репозитория (ветка master) каталоги ru и en. Затем просто переношу в каждый из них все .md-файлы, относящиеся к двум вариантам книги. Причём, что удобно, в сами эти файлы, равно как и в их структуру, я не вношу никаких изменений, просто переношу.

Затем в корне репозитория создаю файл LANGS.md и пишу в него следующее:

* [По-русски](ru/)
* [in English](en/)

То есть обыкновенный Markdown-список с языковыми ссылками, каждая из которых ведёт внутрь своего языкового каталога.

Всё. Теперь собираю книгу с помощью команды gitbook точно так же, как было описано выше. Далее, как обычно, переношу это хозяйство в ветку gh-pages, коммичу-пушу — и в результате, при заходе на страницу, вижу вот это:



Соответственно, вот русская версия:



а вот и английская:



Кстати, обратите внимание на улучшенный вид. Благодаря обновлению gitbook с версии 0.1.0 до версии 0.1.2:
— появилась листалка страниц в обе стороны (привязанная к клавишам Влево-Вправо),
— появился поиск в верхнем левом углу.

Кроме того, небольшие изменения, внесённые мною в шаблон темы:
— улучшили шрифт (спасибо Google Fonts),
— расположили заголовки по центру,
— выровнили текст по ширине (всё-таки для книги так лучше).

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

Альтернативы

GitBook великолепен, но есть и другие.

MkDocs. Почти аналог GitBook, с той лишь разнице, что работает не на JS, а на Python. Концептуально всё то же самое: собираем .md-файлы по структуре книги, скармливаем это утилите mkdocs — и готово. Преимущество перед GitBook вижу одно: есть готовый набор тем для создаваемого сайта.

Sphinx. Питоновский инструмент, использует собственный формат разметки (не Markdown). На выходе, помимо HTML, могут быть документы LaTeX, ePub).

Так что выбор есть. Как верно заметили ниже, эти инструменты страшно недооценённые.