Простейший блог на Github Pages

Обновлено 2019-04-21 +00:00.

В предыдущий раз был проведён небольшой обзор способов вести заметки в интернете, и был выбран сервис Github Pages, являющийся частью Github.
Здесь простыми словами описано, как начать на Github Pages свой блог/сайт.

Необходимые требования:

• иметь аккаунт на Github,
• знать markdown-разметку (в диалекте kramdown, CommonMark¹ или Redcarpet),
• уметь нажимать на кнопки в интерфейсе Github.

В этом случае Github используется как продвинутый онлайн-редактор, никакого знания git не требуется. Отмечу, что знание markdown не является обязательным. На Github Pages можно загрузить "обычный", "статический" сайт из html-, css- и js-файлов (но никакого php). Однако писать тексты на markdown намного проще, чем на HTML и даже проще, чем редактировать страницы в Википедии, а об остальном позаботиться Jekyll².

Как начать

Для создания блога c нуля надо сделать несколько шагов:

1. Зарегистрироваться на Github.
2. Выбрать вид будущего блога (тему для Jekyll - движка, формирующего сайт), можно взять за основу другой блог. Список будет ниже.
3. Cделать копию этого блога/темы и изменить имя репозитория.
4. Изменить пару строк (как правило) в файле настроек _config.yml и удалить старый контент,
5. Profit! Готово, можно писать.

Конечно, во всём есть нюансы, но в простейшем случае всё действительно просто. Пройдём шаги по порядку.

1. Регистрация на Github

Нужно зайти на сайт Github и выбрать Signup ("Зарегистрироваться") в правом верхнем углу. Не путать с Signin - "Войти" для уже зарегистрированных пользователей!

Выбирайте имя аккаунта тщательно: сделанный сайт/блог будет находится по адресу <имя_аккаунта>.github.io. Само имя ещё понадобится на третьем шаге.

Немного терминологии. Каждый "проект" в Github хранится в своём "репозитории" (можно считать эти слова синонимами). У репозитория/проекта есть своё имя в формате <имя_аккаунта>/<имя_репозитория>, и своё хранилище файлов/папок. Сайт пользователя хранится в одном из таких репозиториев. Например, содержимое этого сайта хранится в репозитории atremba/atremba.github.io. Имя репозитория может быть произвольным, но для сайта пользователя он должен иметь специальное имя³.

2. Выбор оформления

Надо найти на Github подходящую тему для движка Jekyll или готовый блог на Jekyll. Рекомендую начать с простых тем: poole⁴, Jekyll Now или пройтись по списку плагинов. Обычно в файле README.MD указывают, какие необходимые действия нужны после копирования сайта.

3. Копирование готового сайта/блога/темы

Нажать большую зелёную кнопку Fork и через несколько секунд получить в своём аккаунте копию репозитория. Зайти в его настройки и поменять имя на <имя_аккаунта>.github.io, подставив имя своего аккаунта.

4. Настройка сайта: новое имя и автор

Чтобы проверить, что сайт активирован, в настройках⁵ репозитория в разделе GitHub Pages надо убедиться, что источником сайта является ветка master, и мелким шрифтом написано

User pages must be built from the master branch.

Что означает

Сайт пользователя должен формироваться из ветки master.

Далее надо настроить ключевые параметры под себя (пример для poole).

• в корне репозитория найти файл _config.yml и отредактировать его:
  • изменить название сайта и подпись в полях title: и tagline:,
  • изменить значение полей в url: и baseurl: на https://<имя_аккаунта>.github.io, а также изменить данные автора в блоке (author:).
    Не удаляйте отступы в два пробела начале строк! Файл _config.yml не просто текстовый, а подчиняется стандарту YAML.
• удалить все файлы скопированного блога в папке _posts, плагиат это плохо,
• удалить файл CNAME из корня - это привязка к своему домену; для сайта на Github Pages он не нужен.

Почти всё сделано. На этом моменте можно проверить, что сайт уже доступен по адресу http://<имя_аккаунта>.github.io. Должна отображаться страница с новым названием сайта, но без записей.

5. Создание записей (постов)

Подготовка завершена, можно создавать свои записи, которые автоматически будут транслироваться в сайт.

Jekyll различает два типа файлов с информацией: статические файлы, соответствующие таким страницам, как "О сайте", "Список планов" и т.п., и датированные записи, формирующие "блоговую" начинку сайта. Каждая запись соответствует файлу с расширением .md, который находится в папке _posts и чьё имя начинается с даты (она используется для сортировки): 2019-04-11-<имя-без-пробелов>.md. Сам файл имеет содержание вида

---
layout: post
title: Начинаем блог
---

Моя первая запись!

В заголовке в поле layout: указан шаблон страницы, а в поле title: название записи. Оба этих поля не обязательны, можно сделать и пустую запись (исходный код). После второй отбивки --- следует тело записи в формате markdown.

Пошаговое создание файла в репозитории из примера выше (с картинками)

Создать файл в Github просто: надо зайти в свой аккаунт, затем перейти в свой репозиторий <имя_аккаунта>/<имя_акаунта>.github.io, войти в папку _posts и создать новый файл:

1. Выбор места и кнопка создания файла
2. Имя файла и первичное содержимое
3. Создание файла
4. Смотрим сайт <имя_аккаунта>.github.io и видим результат:
5. Если надо что-то изменить, возвращаемся на Github в репозиторий и кликаем на файл
6. Предпросмотр файла. Кнопка редактирования
7. Изменение содержимого
8. И повторный "коммит"-сохранение⁶
9. Окончательный результат (обновление сайта на Github происходит с небольшой задержкой - с полминуты)

К сожалению, часто обновлять сайт таким образом не получится, у Github Pages есть мягкое ограничении 10 "сборок" сайта в час. Для отладки удобно установить локальную копию сайта.

Далее можно:

• установить локальную версию Jekyll для отладки изменений и записей,
• познакомиться с git (в плане) в контексте работы с сайтом на Github Pages,
• изучить возможности markdown (в плане) для редактирования текстов,
• разобраться с Jekyll:
  • сделать начальную настройку сайта,
  • погружаясь в глубины Jekyll по настройке блога (в плане), для изменения внешнего вида или структуры,
  • изучая Liquid - внутренний "движок" Jekyll, и
  • меняя внешний вид в HTML-коде (в плане).

Ссылки

• https://help.github.com/en#customizing-github-pages - раздел документации о работе с Jekyll в помощи Github Pages. Весьма подробный и раскрывающий многие нюансы. Актуален.

• http://alexprivalov.org/setup-blog-on-github/ - очень хороший пост, во многом вдохновивший на ведение блога именно на Jekyll с темой Poole. Включает установку локального Jekyll (если сходу не получится, см. мою запись о локальной установке).

• https://guides.hexlet.io/jekyll/ - краткое, но содержательное руководство по настройке Jekyll с темой на Bootstrap.

• https://pages.github.com/ - Github pages. Инструкция о настройке прямо на первой странице.

• https://lab.github.com/githubtraining/github-pages - курс на Github Pages для знакомства с Jekyll.

• http://jmcglone.com/guides/github-pages/ - одно из рекомендуемых на сайте Jekyll руководств по установки и использованию Jekyll на Github, с влезанием в HTML неплохим набором ссылок (всё на английском).