В ноябре прошлого года я решил изучить возможность бесплатного ведения блога на хостинге GitHub Pages с помощью генератора статических сайтов Jekyll, создал пробный блог (я использую тему оформления minima) и написал пост об этом.

Про Jekyll я много слышал, но в данном случае меня привлекла возможность попробовать работать с ним без установки самого этого генератора и его зависимостей на свой компьютер. (Намного чаще Jekyll используют с установкой его на свой компьютер. Возможно, в будущем я попробую и такой вариант, он дает больше возможностей.)

За прошедшее время я написал там два десятка постов, дублируя их в ЖЖ. Параллельно я вносил изменения в тему оформления minima (я сделал ее форк [копию] и работаю в нем). В этом и следующем посте/постах я хочу описать самые интересные из этих изменений и вообще некоторые особенности работы с таким блогом.

Коротко про общее устройство Jekyll

Jekyll позиционируется как генератор статических сайтов. Сайт — это набор файлов, которые называют «страницами». Эти файлы-страницы могут находиться как в одной папке, так и в целом дереве папок с возможной вложенностью. Блогом могут называть как отдельный сайт, так и часть какого-либо сайта. То есть с технической точки зрения между постами блога и страницами сайта нет разницы.

В начале работы с Jekyll обычно вы сразу получаете проект со сложной структурой папок и большим количеством файлов. По сути это одна большая, уже полностью готовая к работе программа и данные для нее, разделенные на множество файлов. Программисты часто называют такую программу «фреймворком» (по-русски «каркас»), потому что от вас требуется лишь добавлять новые данные в правильные места и правильно настраивать программу, а не писать ее с нуля.

При этом желающие могут кроме добавления данных изменять/дополнять и сам фреймворк, но для этого нужны знания соответствующих языков программирования и разметки, а также знания об устройстве этого фреймворка.

Обработка файлов генератором и публикация

После того, как вы внесли нужные изменения в файлы проекта и добавили новые данные, для их публикации требуется запустить их обработку (сборку, по-английски «build») генератором Jekyll и выполнить развертывание (по-английски «deployment») полученных в результате сборки файлов, то есть их копирование на сервер хостинга.

По умолчанию эти две операции проделывает сам хостинг GitHub Pages, как только вы внесете какие-либо изменения в файлы проекта. Для этого автоматически вызывается встроенный рабочий процесс (workflow) с названием pages build and deployment. Вызовы этого процесса можно отследить в разделе/вкладке «Actions» репозитория (верхнее меню) с файлами проекта. Тут подробнее.

Сборка и развертывание/публикация не происходят мгновенно. Обычно эти действия занимают несколько минут и обновления на сайте появятся не сразу после внесения изменений в файлы проекта.

Не всегда этот процесс заканчивается успешно. Результаты развертываний можно отследить в разделе «Deployments» репозитория (панель справа). В случае неудачи имеется возможность перезапустить процесс (workflow) целиком или перезапустить отдельные работы (job), из которых состоит процесс. Тут подробнее.

В случае необходимости (такое иногда бывает) можно временно отключить (без полного удаления, которое тоже возможно) любой процесс отдельно или все процессы сразу. Для созданных владельцами репозитория процессов об этом можно прочесть в документации GitHub тут. Отключение автоматического процесса pages build and deployment тоже возможно: это делается в настройках Settings репозитория, в разделе Pages.

Создание страниц сайта/блога

Хоть технически между постами блога и страницами сайта нет разницы, при работе с Jekyll мы их разделяем. Документация на официальном сайте: pages (страницы сайта), posts (посты блога).

Для создания страницы сайта или поста блога достаточно создать текстовый файл (обычно в кодировке UTF-8) с расширением .html или .md с содержимым на языках разметки HTML или Markdown соответственно и поместить этот файл в нужную папку. Я помещаю страницы сайта в корневую папку проекта. После автоматической публикации они становятся видны посетителям моего сайта/блога.

В начале страницы сайта или поста блога в Jekyll обычно (но не всегда) помещается раздел метаданных, который называется «Front Matter». В этом разделе обычно размещают название макета layout, название страницы title и другую важную информацию, которую Jekyll использует при сборке (build) проекта. Например, здесь может быть указан так называемый permalink (постоянная ссылка), который участвует в формировании адреса данной страницы.

На моем сайте/блоге изначально были в корневой папке страницы index.md (главная страница сайта, без постоянной ссылки) и about.md (о сайте, постоянная ссылка: /about/). index.md я переименовал в index.html (потребовалось для включения пагинации, об этом будет далее). Еще я добавил страницу tags.html (архив меток, постоянная ссылка: /tags/). Вот какие адреса у этих страниц:

Если вы хотите, чтобы существующая страница сайта появилась в виде пункта в верхнем меню при использовании темы оформления minima, добавьте информацию об этом в файл с настройками _config.yml, который находится в корневой папке проекта. Фрагмент этого файла с нужными настройками у меня (отступы/пробелы имеют значение):

minima:
  nav_pages:
    - tags.html
    - about.md

Названия пунктов меню будут взяты из разделов «Front Matter» соответствующих файлов.

Как оказалось, выбор языка разметки (HTML или Markdown) зависит от содержимого, которым вы хотите наполнить данную страницу сайта или пост блога. Для страницы/поста с преимущественно текстовым содержимым (у меня это все посты блога и страница about.md) удобнее использовать Markdown. Для страниц с большим количеством кода на языке программирования Liquid удобнее использовать HTML (у меня это страница tags.html).

Вообще, нужно понимать, что все файлы с расширениями .html и .md являются с точки зрения Jekyll заготовками (шаблонами) будущих готовых страниц сайта/блога. Готовые страницы будут получены в процессе их сборки (build) из заготовок (шаблонов). В заготовках (шаблонах) традиционно, как и в других подобных генераторах/фреймворках, кроме языка разметки текста используется какой-либо язык программирования. В данном случае авторы Jekyll на эту роль выбрали язык программирования Liquid (существует официальный сайт с документацией по языку).

Посты блога

Как уже было сказано ранее, посты блога технически не отличаются от страниц сайта. Обычно это текстовые файлы в кодировке UTF-8 с расширением .md, написанные на языке разметки Markdown. В начале каждого файла с постом присутствует раздел «Front Matter», описанный выше, в котором содержится название макета layout, название поста title и другая информация о посте.

Markdown можно назвать упрощенной версией языка разметки HTML. Упрощен он был специально для людей, пишущих тексты для публикации в интернете. То есть для блогеров, журналистов, писателей и так далее. В нашем случае следует использовать диалект Markdown для GitHub.

Файлы с постами помещают в подпапку _posts в корневой папке проекта. Названия файлов с постами составляются по определенному шаблону. Вот для примера названия трех последних на данный момент файлов с постами у меня:

2026-06-13-primes-seive-eratosthenes.md
2026-06-27-decompose-on-primes.md
2026-07-03-plantuml.md

Указываются год, месяц и дата публикации. Затем указывается название поста. В качестве разделителей слов и чисел используют дефисы. Такие названия у меня после автоматической публикации трансформируются в следующие адреса:

В рассматриваемом случае посты можно создавать и писать прямо из браузера на сайте веб-сервиса GitHub с помощью веб-интерфейса. Там есть возможность предпросмотра для файлов на языке разметки Markdown.

Однако, мне гораздо удобнее писать текст поста у себя на компьютере. Как оказалось, редактор VSCode, который мы используем в колледже, имеет встроенную функцию предпросмотра для файлов на языке Markdown. Пишу посты теперь в этом редакторе. Готовый файл с постом можно отправить на GitHub через веб-интерфейс, но я предпочитаю использовать систему контроля версий git.

В клонированном (скопированном) репозитории у меня на компьютере создание коммита с новым постом и его отправка на GitHub занимают полминуты или меньше. Как только GitHub получает новый коммит, он автоматически запускает сборку и публикацию проекта на хостинге GitHub Pages.

Вот как выглядит написание поста в редакторе VSCode у меня на компьютере с одновременным предпросмотром во вкладке справа (картинку можно открыть в реальном размере щелчком левой кнопкой мыши по ней):

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

Практически все студенты, наоборот, во всех программах и на всех сайтах, где это возможно, выбирают темные темы оформления. Как говорится, «темнота — друг молодежи». У меня есть множество гипотез с объяснением этого явления, но я пока не готов остановиться на какой-то одной или хотя бы нескольких из них.

Многие объясняют это тем, что якобы в темной теме оформления меньше устают глаза или что в темной теме удобно работать ночью. Я не согласен ни с первым (у меня, наоборот, глаза быстрее устают при темной теме), ни со вторым (ночью, когда свет в комнате выключен, при темной теме не видно клавиш клавиатуры, нередко это бывает важно).

Продолжение следует

В следующем посте я постараюсь рассказать, какие добавления в тему minima я уже сделал для своего блога и какие планирую.