Установка Hexo и размещение сайта на Github Pages

Это страница очень рекурсивна: это страница-пример выполнения инструкций на этой странице! Оригинал записи находится на lisakov.com.

Hexo — это генератор статических сайтов, подобный Jekyll, Pelican, Octopress, Hugo и т.д.

Что такое генераторы статических сайтов и зачем они нужны?

Сайт, который Вы читаете прямо сейчас — статический. Все странички здесь — это обычные html файлы. Большинство статических журналов создаются с помощью различных генераторов статических сайтов.

Зачем они нужны, эти генераторы? Ведь можно, например, написать самому CSS- и html-код для каждой страницы своего сайта. Но при добавлении, например, записи в журнал каждый раз придётся переделывать страницу со списком записей, ленту записей, ссылки под статьёй (на следующую и предыдущую статью) и пр. Всё это и многое другое автоматически умеют делать генераторы, обширный список которых можно найти тут: staticsitegenerators.net.

Пользуясь генератором, Вы создаёте обычные текстовые файлы для записей и страниц, html-кода в них нет. Очень популярным форматом (но не единственным) является язык разметки Markdown (по ссылке много понятных примеров). Когда Вы довольны структурой сайта и содержанием записей, Вы запускаете генератор. Он съедает ваши текстовые файлы и генерирует html-файлы, которые остаётся только выложить на сайт.

Все эти генераторы очень похожи один на другой, причём для пользователя совершенно неважно, на чём они работают: ruby, python, javascript, go или что-то ещё. Мне было интересно посмотреть на несколько генераторов, и я немного поигрался с Octopress, Hexo и Hugo. Из отличий я заметил только скорость генерации сайта. Октопрессу для того, чтобы сгенерировать мой сайт, нужно 2-3 секунды, Hexo — 1-2 секунды, а Hugo справляется за десятую долю секунды. Ещё легче всего было установить Hugo: для Ubuntu существует .deb пакет, который легко устанавливается через менеджер приложений. А по сути все эти генераторы одинаковые.

Сайт, который Вы сейчас читаете, был создан с нуля с помощью Hexo и размещён на Github Pages примерно за полчаса. Документация по Hexo на официальном сайте неплохая, но всё же там отсутствуют некоторые необходимые вещи, которые приходилось выискивать.

Итак, поехали. Устанавливаем генератор статических сайтов Hexo на Линукс и делаем сайт доступным по адресу имя_сайта.github.io. В результате выполнения действий, указанных ниже, Вы получите точно такой же сайт, как этот. Если всё пойдёт гладко, то меньше чем через час Вы уже сможете разослать ссылки на свой новый блог своим друзьям. Уже потом Вы наверняка захотите сменить тему, добавить комментарии, Google Analytics и прочее, руководствуясь инструкциями с официального сайта Hexo. Всё это делается довольно просто.

Установка Hexo

  1. Установите git, если он ещё не установлен. В Убунту это можно сделать так (для инструкций для других ОС следуйте по ссылке):

    sudo apt-get install git
    
  2. Нам нужен node.js. Лучше всего будет установить Node Version Manager (nvm), а из него уже будет легко пользоваться необходимой версией node.js. Чтобы установить nvm, воспользуйтесь либо утилитой wget,

    wget -qO- https://raw.github.com/creationix/nvm/master/install.sh | sh
    

    либо утилитой curl:

    curl -L https://raw.github.com/creationix/nvm/master/install.sh | sh
    

    После этого появится директория ~/.nvm (как обычно, чтобы её увидеть в терминале, надо выполнять ls -a, т.к. имя её начинается с точки). Чтобы начать пользоваться nvm, нужно перезапустить терминал (иногда, говорят, нужна даже перезагрузка). Затем нужно выполнить команды:

    . ~/.nvm/nvm.sh
    

    чтобы активировать nvm, и

    nvm install 0.12
    
  3. Наконец, устанавливаем Hexo:

    npm install -g hexo-cli
    

    Если терминал ругается и не выполняет команду, попробуйте сначала сделать nvm use 0.12.

    На этом установка закончена. Если на каком-то этапе возникли трудности, обязательно дайте знать в комментариях, попробуем разобраться вместе.

    Приступаем к настройке.

Базовая настройка и использование Hexo

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

Создайте директорию, где будет лежать hexo, войдите в неё и выполните hexo init .. Для определённости установим hexo в /home/user, т.е. в ~/.

mkdir ~/hexo
cd ~/hexo
hexo init .

не забудьте точку в последней команде, она означает текущую директорию. Теперь в ~/hexo должно появиться:

.
├── _config.yml
├── package.json
├── scaffolds
├── scripts
├── source
|   ├── _drafts
|   └── _posts
└── themes

Чтобы установить необходимые модули, надо выполнить

npm install

после чего появится новая директория node_modules со стандартными модулями. Туда же будут устанавливаться новые модули.

Теперь, чтобы посмотреть результат генерации файлов на локальной машине, выполните

hexo server

Если всё в порядке, то появится сообщение: INFO Hexo is running at http://0.0.0.0:4000/. Press Ctrl+C to stop. Введя этот адрес в браузере (или щёлкнув на него средней кнопкой мыши) можно будет увидеть, что получилось. А получиться должно так, что на первой странице будет запись под заголовком «Hello World». Она появилась, потому что в source/_posts/ лежит файл hello-world.md. Откройте его в любимом текстовом редакторе, сравните с готовым результатом в браузере, и через пару минут пристального всматривания Вы поймёте, что такое язык разметки Markdown и как с его помощью писать записи. Добавить новую запись можно так:

hexo new post 'my-first-post'

Эта команда создаёт файл my-first-post.md в source/_posts/ со стандартной шапкой:

title: my-first-post
date: 2015-06-16 11:49:05
tags:
---

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

Вот и новая запись появилась. Блог готов. Осталось теперь разместить его в интернете. Это можно сделать быстро и бесплатно с помощью сервиса Github Pages. Ещё у меня есть запись с подробной информацией на тему хостингов, доменов и всего необходимого для разворачивания сайта. Ниже я расскажу, как запустить сайт с адресом логин.github.io и удобно заливать туда сайт, используя Hexo.

Размещаем сайт в интернете.

  1. Регистрируйтесь на github.com и входите в свой аккаунт. Активируйте аккаунт с помощью инструкций в письмах, которые придут по указанному при регистрации адресу.

  2. Создайте новый репозиторий (ссылка сработает только для зарегистрированного и вошедшего пользователя) с таким названием: логин.github.io. Например, мой логин на гитхабе — pozitron57, поэтому репозиторий я назвал pozitron57.github.io. Чтобы репозиторий начал работу, надо создать в нём какой-нибудь файл. Github предложит создать README.md, так что просто щёлкните на эту ссылку и впишите что-нибудь. Нажмите кнопку «Commit new file». Готово, репозиторий создан.

  3. Итак, Hexo установлен и генерирует страницы, а наш репозиторий на github.com готов к размещению сайта. Осталось научиться сайт с помощью Hexo заливать на github.com. Установим необходимый модуль для Hexo (при этом надо находиться там, куда установлен Hexo, например, в ~/hexo:

    npm install hexo-deployer-git --save
    

    Затем открывайте _config.yml, что лежит в ~/hexo, ищите параметры url и deploy и приводите их к такому виду:

    url: http://логин.github.io
    
    deploy:
      type: git
      repo: https://github.com/логин/логин.github.io
    

    Поменяйте логин на ваш логин на Github. Затем выполняйте

    hexo generate
    

    В результате появится директория ~/hexo/public со сгенерированными html-файлами. Чтобы отправить эти файлы на Github, выполните

    hexo deploy
    

    Будет предложено ввести имя пользователя и пароль. После сообщения INFO Deploy done: git открывайте в браузере http://логин.github.io. Там должен появиться журнал, сгенерированный Hexo. Если выскакивает ошибка 404, то проверьте сначала, обновился ли репозиторий. Просмотрите его в браузере по адресу http://github.com/логин/логин.github.io (или можно просто в своём гитхабовском аккаунте выбрать нужный репозиторий). Если там лежит файл index.html и директории archives, css, js, то проверьте почту, которую указывали при регистрации на github и убедитесь, что выполнили все инструкции оттуда, нажали все необходимые ссылки, чтобы активировать аккаунт. Если это всё равно не помогло, внимательно проделайте все шаги заново.

    Вместо последовательного выполнения hexo generate и hexo deploy можно выполнять
    hexo generate --deploy или hexo generate -d.

    Итак, бесплатный статический блог развёрнут. На нём нет рекламы, его страницы легки. Вы можете менять темы, настраивать темы, устанавливать плагины. Такие сайты делают интернет быстрее и лучше!

    Ещё одна хорошая новость: если захочется купить себе доменное имя (lisakov.com, например, стоит 600 рублей в год), его будет очень просто прикрутить к Github Pages. Достаточно будет создать файл с именем CNAME в репозитории, в содержании которого нужно указать указать желаемый домен без http://, например, sitename.com. Подробнее можно узнать на сайте Github Pages. Чтобы создать файл CNAME с помощью Hexo, просто создайте ~/hexo/source/CNAME с необходимым содержанием. При выполнении hexo deploy этот файл будет обновляться на Github Pages.

    Что, если Вам надоест Hexo и захочется воспользоваться другим генератором статических сайтов? Нет ничего проще: установите любой другой генератор, скопируйте все записи из source/_posts туда, где хранятся записи у нового генератора. Готово! К примеру, эта запись и её оригинал на lisakov.com генерируются из одного и того же текстового файла (с точностью до шапки и смысловых различий), потому что и Octopress, используемый на lisakov.com, и Hexo, использованное тут, умеют работать с языком разметки Markdown.

    Если у Вас что-то не получилось или есть вопросы, обязательно пишите в комментариях.

Сменить тему

Темы для Hexo доступны красивые. Вот они. Выбирайте приглянувшуюся и следуйте инструкциям по установке. Скажем, вы выбрали тему Light. Заходите в директорию с Hexo и выполняйте:

git clone git://github.com/tommy351/hexo-theme-light.git themes/light

Чтобы активировать тему, измените параметр theme: в _config.yml

theme: light

Известные проблемы.

  • Если на команды, начинающиеся с nvm, npm или hexo, терминал ругается, попробуйте сначала выполнить

    nvm use 0.12
    
  • Если Вы внесли изменения в запись или внешний вид темы, а при обновлении сайта с помощью hexo deploy эти изменения не отображаются, попробуйте перед генерацией сайта удалить директорию public. Затем снова выполните hexo generate -d.