В этой статье рассказано, как бесплатно за полчаса с нуля создать сайт и сделать его доступным по адресу sitename.github.io.
Hexo — это генератор статических сайтов, подобный Jekyll, Pelican, Octopress, Hugo и т.д.
Сайт, который Вы читаете прямо сейчас — статический. Все странички здесь — это обычные html файлы. Большинство статических журналов создаются с помощью различных генераторов статических сайтов.
Зачем они нужны, эти генераторы? Ведь можно написать самому CSS- и html-код для каждой страницы своего сайта. Но при добавлении, например, записи в журнал каждый раз придётся переделывать страницу со списком записей, ссылки под статьёй (на следующую и предыдущую статью), добавлять новые категории и пр. Всё это и многое другое автоматически умеют делать генераторы, обширный список которых можно найти тут: staticsitegenerators.net.
Пользуясь генератором, Вы создаёте обычные текстовые файлы для записей и страниц, html-кода в них нет (html-теги, разумеется, можно использовать при желании). Очень популярным форматом (но не единственным) является язык разметки Markdown. Генератор съедает ваши текстовые файлы и генерирует html-файлы, которые остаётся только выложить на сайт.
Все эти генераторы очень похожи один на другой. Если всё устраивает, то лезть в код не придётся, и тогда пользователю неважно, на чём они написаны: ruby, python, javascript, go или что-то ещё. Мне было интересно посмотреть на несколько генераторов, и я пробовал Octopress, Hexo, Hugo и Pelican. Из отличий я заметил разницу в скорости (сильно зависит от количества и объёма записей, темы и плагинов, так что сравнение некорректное): Октопрессу для того, чтобы сгенерировать мой сайт на текущий момент, нужно 2-3 секунды, Hexo — 1-2 секунды, а Hugo справляется за десятую долю секунды. Легче всего было установить Hugo: для Ubuntu существует .deb пакет, который легко устанавливается через менеджер приложений.
На момент написания этой записи страницы моего сайта генерировались с помощью Octopress (в конце 2015 года я перешёл на Hexo). На его официальном сайте документация очень хорошая и понятная, поэтому мне не пришло в голову писать заметку об установке Octopress. Документация по Hexo оформлена неплохо, но там отсутствуют некоторые необходимые вещи, которые приходилось выискивать.
Итак, поехали. Устанавливаем генератор статических сайтов Hexo и заливаем его на Github Pages. Посмотреть, что получится в результате описанных ниже манипуляций (если всё пойдёт гладко, то достаточно будет получаса), можно тут: pozitron57.gihtub.io.
Установите git, если он ещё не установлен. В Убунту это можно сделать так (для инструкций для других ОС следуйте по ссылке):
sudo apt-get install git
Нам нужен 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
Наконец, устанавливаем Hexo:
npm install -g hexo-cli
Если терминал ругается и не выполняет команду, попробуйте сначала сделать nvm use 0.12.
На этом установка закончена. Если на каком-то этапе возникли трудности, обязательно дайте знать в комментариях, попробуем разобраться вместе.
Приступаем к настройке.
По настройке уже можно пользоваться документацией с сайта, проблем у меня не возникло. Для полноты картины приведу здесь необходимый минимум команд, но за полной информацией отправляйтесь на официальный сайт Hexo.
Создайте директорию, где будет лежать hexo, войдите в неё и выполните hexo init .. Для определённости установим hexo в /home/user, т.е. в ~/.
1 | mkdir ~/hexo |
не забудьте точку в последней команде, она означает текущую директорию. Теперь в ~/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/ со стандартной шапкой:
1 | title: my-first-post |
С таким же успехом его можно было создать вручную. Добавьте после шапки (т.е. после трёх дефисов) пару строк, сохраните файл и снова выполните hexo server. То, что вы написали, будет обработано процессором Markdown. Подробнее про этот язык разметки я написал тут.
Вот и новая запись появилась. Блог готов. Осталось теперь разместить его в интернете. Это можно сделать быстро и бесплатно с помощью сервиса Github Pages. Ещё у меня есть запись с подробной информацией на тему хостингов, доменов и всего необходимого для разворачивания сайта. Ниже я расскажу, как запустить сайт с адресом логин.github.io и удобно заливать туда сайт, используя Hexo.
Регистрируйтесь на github.com и входите в свой аккаунт. Активируйте аккаунт с помощью инструкций в письмах, которые придут по указанному при регистрации адресу.
Создайте новый репозиторий (ссылка сработает только для зарегистрированного и вошедшего пользователя) с таким названием: логин.github.io. Например, мой логин на гитхабе — pozitron57, поэтому репозиторий я назвал pozitron57.github.io. Чтобы репозиторий начал работу, надо создать в нём какой-нибудь файл. Github предложит создать README.md, так что просто щёлкните на эту ссылку и впишите что-нибудь. Нажмите кнопку «Commit new file». Готово, репозиторий создан.
Итак, Hexo установлен и генерирует страницы, а наш репозиторий на github.com готов к размещению сайта. Осталось научиться сайт с помощью Hexo заливать на github.com. Установим необходимый модуль для Hexo (при этом надо находиться там, куда установлен Hexo, например, в ~/hexo:
npm install hexo-deployer-git --save
Затем открывайте _config.yml, что лежит в ~/hexo, ищите параметры url и deploy и приводите их к такому виду:
1 | url: http://логин.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 и всё остальное из директории ~/hexo/public, то проверьте почту, которую указывали при регистрации на github и убедитесь, что выполнили все инструкции оттуда, нажали все необходимые ссылки, чтобы активировать аккаунт. Если это всё равно не помогло, внимательно проделайте все шаги заново.
Вместо последовательного выполнения hexo generate и hexo deploy можно выполнять hexo generate --deploy или hexo generate -d.
Итак, бесплатный статический блог развёрнут. На нём нет рекламы, его страницы легки. Вы можете менять темы, настраивать темы, устанавливать плагины. Такие сайты делают интернет быстрее и лучше!
Ещё одна хорошая новость: если захочется купить себе доменное имя (lisakov.com, например, стоит 600₽ 890₽ в год), его будет очень просто прикрутить к Github Pages. Достаточно будет создать файл с именем CNAME в репозитории, в содержании которого нужно указать указать желаемый домен без http://, например, sitename.com. Подробнее можно узнать на сайте Github Pages. Чтобы создать файл CNAME с помощью Hexo, просто создайте ~/hexo/source/CNAME с необходимым содержанием. При выполнении hexo deploy этот файл будет обновляться на Github Pages.
Что, если Вам надоест Hexo и захочется воспользоваться другим генератором статических сайтов? Нет ничего проще: установите любой другой генератор, скопируйте все записи из source/_posts туда, где хранятся записи у нового генератора. Готово! К примеру, эта запись и её двойник на pozitron57.github.io генерируются из одного и того же текстового файла (с точностью до шапки и смысловых различий), потому что и Octopress, используемый здесь использованный здесь раньше, и Hexo, использованное на pozitron57.github.io, умеют работать с языком разметки Markdown.
Если у Вас что-то не получилось или есть вопросы, обязательно пишите в комментариях.
Темы для Hexo доступны красивые. Вот они, ещё больше их здесь, хотя и написано, что страница устаревшая. Выбирайте приглянувшуюся и следуйте инструкциям по установке. Скажем, вы выбрали тему Light. Заходите в директорию с Hexo и выполняйте:
git clone git://github.com/tommy351/hexo-theme-light.git themes/light
Чтобы активировать тему, измените параметр theme: в _config.yml
theme: light
Например, хочется, чтобы страница site.com/blog/ генерировалась из отдельного шаблона. Зайдите в themes/<название темы>/layout/, поглядите на структуру вашей темы. page.ejs — шаблон для страниц (markdown-файлы, у которых указано layout: page), post.ejs — шаблон для записей и т.д. Создайте новый шаблон blog.ejs и наполните его, модифицируя что-то из существующих шаблонов или написав с нуля. Теперь создайте файл source/blog/index.md, наверху в параметрах укажите layout: blog.
Чтобы вставить содержимое source/blog/index.md, надо в blog.ejs использовать переменную <%- page.content %>.
Если на команды, начинающиеся с nvm, npm или hexo, терминал ругается, попробуйте сначала выполнить
nvm use 0.12
Если Вы внесли изменения в запись или внешний вид темы, а при обновлении сайта с помощью hexo server или hexo deploy эти изменения не отображаются, попробуйте перед генерацией сайта выполнить hexo clean. Если не помогло, попробуйте, сделав бекап на всякий случай, удалить из корня db.json (если есть). Затем снова выполните hexo generate -d.
Если при заходе на http://127.0.0.1:4000 браузер открывает поисковой запрос с таким текстом, то можно заходить на localhost:4000.
Например, хочется положить js, html или ещё какой-то файл в директорию source. Проблема в том, что Hexo будет пытаться обработать эти файлы, что чаще всего будет вызывать ошибки и всегда занимать время. Чтобы избежать обработку, например, js-файлов, надо в _config.yml указать: skip_render: '**/*ejs'. Так везде советуют, но мне это не помогло. Оказалось, что можно положить эти файлы не в source, а в themes/<название темы>/source, тогда Hexo не будет пытаться их обработать.
Использование {% include_code %} позволяет вставить код в запись, который лежит по адресу code_dir, определённому в _config.yml. Очевидно, что если code_dir находится внутри source, то Hexo будет пытаться обработать его, что, безусловно, в высшей степени странно. У меня всё работает с такими настройками:
1 | code_dir: ../themes/wixo/source/code |
и в файле node_modules/hexo/lib/plugins/tag/include_code.js я заменил
caption = '<span>' + title + '</span><a href="' + ctx.config.root + codeDir + path + '">View raw</a>';
на
caption = '<span>' + title + '</span><a href="/code/' + path + '">View raw</a>';
чтобы по ссылке View Raw действительно можно было посмотреть голый текст кода.