Anna Leonova

Anna Leonova

That’s me!


jekyll-now для персонального блога

12 мин на чтение

Небольшой гайд для чайников про запуск своего блога на GitHub Pages, несколько полезных твиков для добавления в блог архива, тегов и новых иконок.

jekyll-now для персонального блога

Для ведения небольшого (хотя большой тоже можно) личного блога с заметками и статьями отлично походят движки статических сайтов или flat-file CMS (Jekyll, Grav CMS, Kirby, Hugo и тысячи их).
Преимуществом Jekyll является то, что его из коробки поддерживает GitHub Pages. Значит, что не нужно возиться с установкой ПО, запускать веб-серверы и пр, достаточно создать аккаунт GitHub, создать репозиторий для сайта, закинуть туда файлы сайта (или форкнуть репозиторий) … и все!
Сами посты блога можно писать в Markdown в любом удобном, любимом редакторе или прямо через веб-интерфейс GitHub.
Еще один гайд на английском языке: aleksandrhovhannisyan.com (2020 г.).

Создаем аккаунт и форкаем репозиторий

Нам нужно:

  1. зарегистрировать аккаунт на github.com. Видео на русском языке, как создавать аккаунт, например, вот это, спасибо @ITDoctor;
  2. форкнуть репозиторий jekyll-now (или мой репозиторий). В этом репозитории самый простой базовый блог, который дальше можно редактировать. В нем есть парочка другая багов, но их нетрудно исправить. Чтобы форкнуть репозиторий (см. короткую анимацию из репозитория автора jekyll-now):
    1. нужно в верхнем правом углу (где количество просмотров и звезд) нажать кнопку Fork;
    2. дождаться пока репозиторий скопируется в ваш аккаунт;
    3. открыть репозиторий в вашем аккаунте и перейти на вкладку Settings;
    4. поменять имя (Repository name) на yourgithubusername.github.io, где yourgithubusername - ваше имя на GitHub (это обязательный формат, иначе сайт автоматически работать не будет).
  3. сайт с блогом будет доступен по ссылке https://yourgithubusername.github.io, где yourgithubusername - имя вашего аккаунта github. GitHub Pages ребилдит сайт каждый 10 мин. или при изменении файла _config.yml.

Ура, треть дела сделана.

Структура jekyll-now

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

Файл или папка Для чего нужен
_config.yml основные настройки, название блога, ссылки на аккаунты социальных сетей (образец)
style.css основной стилевой файл CSS
index.html домашняя страница. Файлы в корне репозитория (например, about.md, archive.html) также обрабатываются jekyll.
/_layouts шаблоны для основных страниц блога (default.html, page.html,post.html)
/_posts здесь хранятся записи блока в формате markdown. Имя файла должны быть в формате: YYYY-MM-DD-any-post-title.md
/_includes небольшие файлы, содержащие скрипты в формате Liquid
/_sass содержит дополнительные стилевые файлы, написанные на метаязыке Saas

Конфигурация

В файле _config.yml меняем:

  • name: Your Blog Name - название вашего блога
  • description: Your Description Here - краткое название блога (отображается под названием)
  • avatar: https://link - укажите ссылку на ваш логотип/фото. Можно загрузить картинку в папку images в репозитории и ссылка тогда будет вида <https://raw.githubusercontent.com/annjulyleon/yourgithubusername.github.io/master/images/jekyll-logo.png>. Аватарка размером 40x40 px по умолчанию
  • в секции footer-links указываем username или ссылки на аккаунты в соответствующих соцсетях. Иконки с пустыми значениями отображаться не будут. Формат URL (как именно нужно указывать urename) можно посмотреть в файле _includes/svg-icons.html
  • url: https://yourgithubusername.github.io - укажите URL вашего блога
  • baseurl: /repository-name - если вы хотите запускать блог из репозитория проекта http://yourusername.github.io/repository-name, а не репозитория пользователя (просто http://yourusername.github.io), то тут нужно указать название репозитория - /repository-name

Пишем пост

Чтобы добавить пост, создаем файл в формате .md с указанием даты и названия. Дата в названии файла должна быть обязательно, латиница, без пробелов: YYYY-MM-DD-any-post-title.md или 2019-04-24-post-title.md.

В каждом посте в начале файла должна быть секция (в формате YAML), где минимум указываем layout: (один из шаблонов, например page или post) и title: (название, как оно будет отображаться в списке постов и на главной странице). Например:

---
layout: post
title: jekyll-now для персонального блога
---

Небольшой гайд для чайников про запуск своего блога на [GitHub Pages](https://pages.github.com/), несколько полезных твиков для добавления в блог архива, тегов и новых иконок.

Текст поста набран на языке разметки markdown (см. шпаргалку на русском).
Можно редактировать текст прямо в интерфейсе GitHub или сначала писать их с помощью любого Markdown редактора, например Typora, Joplin, плагины для Atom и IDEA и тысячи их.

Добавляем иконки

Можно добавлять нужные иконки соцсетей в формате .svg. Например, я добавила иконки для Telegram и Blogger. Есть официальный гайд на английском языке, привожу его здесь:

  • найдите иконку, которая вам нужна, в формате SVG. Например, можно посмотреть тут;
  • скопировать XML-исходник SVG иконки (открыть в блокноте скачанный SVG файл или нажать кнопку Raw и просмотреть файла SVG в репозитории);
  • нужно сериализовать XML в base64. Для этого можно использовать Notepad++ или онлайн конвертер mobilefish.com. Вставьте XML текст в поле Enter source data*:, укажите значение 0 в поле Max characters per line: (нам не нужно разбивать строки), введите access code с картинке и нажмите Convert;
  • скопируйте сериализованный текст. В файле sass/_svg-icons.scss добавьте строку вида:
&.SOMENAME { background-image: url(data:image/svg+xml;base64,<your encoded string here>); }

SOMENAME - название вашей иконки/соцсети. Вставьте сериализованный текст вместо <your encoded string here>.

Например, здесь две последние строки - для добавления иконок blogger.com и Telegram.

Теперь, чтобы отобразить иконки на страницах блога, нужно отредактировать файл _includes/svg-icons.html, добавив в него строки вида:

{% if site.footer-links.SOMENAME %}<a href="your LINK here/{{ site.footer-links.SOMENAME }}"><i class="svg-icon SOMENAME"></i></a>{% endif %}

где SOMENAME - имя иконки, которое вы назначили на предыдущем шаге, а <your LINK here> - базовая ссылка (t.me для телеграм, blogger.com и т.д.). См. пример.

И наконец, добавим параметр конфигурации для добавленной иконки в _config.yml:

footer-links:
SOMENAME: /yourname

Добавляем страницу со списком постов

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

Добавьте в корень репозитория файл archive.html и скопируйте содержимое:

---
layout: page
title: Archive
permalink: /archive/
---

<section class="archive-post-list">
{% for post in site.posts %}
       {% assign currentDate = post.date | date: "%Y" %}
       {% if currentDate != myDate %}
           {% unless forloop.first %}</ul>{% endunless %}
           <h1>{{ currentDate }}</h1>
           <ul>
           {% assign myDate = currentDate %}
       {% endif %}
       <li><a href="{{ post.url }}"><span>{{ post.date | date: "%B %-d, %Y" }}</span> - {{ post.title }}</a></li>
       {% if forloop.last %}</ul>{% endif %}
   {% endfor %}
</section>

Затем нужно добавить эту страницу в навигацию блога. Для этого откройте файл /_layouts/default.html и найдите секцию <nav>. Добавить страницу:

 <nav>
    <a href="/">Блог</a>
    <a href="/about">Обо мне</a>
    <a href="/archive">Архив</a>
</nav>

Здесь же можно переименовать название пунктов меню.

Страница будет доступна в течение 10 мин.

Добавляем теги и облако тегов

Чтобы проще было ориентироваться в блоге и находить похожие статьи, можно добавить в блог теги. Есть несколько способов реализации тегов и категорий (например, вот с коллекциями), я выбрала самый простой (взяла отсюда).

Добавьте к каждому своему посту в начальную секцию (front matter) теги через пробел или запятую. Например:

---
layout: post
title: jekyll-now для персонального блога
tags: docops jekyll 
---

Затем нужно вывести теги для каждого поста на странице. Мне нравится выводить их перед текстом, сразу после даты, кому-то больше нравится в конце, после поста. В файл /_layouts/post.html/ нужно в начало или конец файла добавить секцию с тегами (секция <small> ниже). Я добавила в секцию с отображением даты (прямо перед <div class="entry">):

<div class="date">
    Written on {{ page.date | date: "%B %e, %Y" }}
	<br />
   <small>
     {% for tag in page.tags %}
     <a href="/tags/{{ tag }}/">{{ tag }}</a>
     {% endfor %}
  </small>
</div>

Теперь нужно создать страницы для каждого тега. на каждой страницы будут перечислены все посты с тегом. Создадим файл _layouts/tagpage.html и добавим содержимое:

---
layout: page # This template inherits from my basic page template
---

<!-- We're going to give each page a tag when we create it.
This will be the title -->
<h1>{{ page.tag | capitalize }}</h1>

<ul>
    {% for post in site.tags[page.tag] %}
    <li>
        {{ post.date | date: "%B %d, %Y" }}: <a href="{{ post.url }}">{{ post.title }}</a>
    </li>
    {% endfor %}
</ul>

Теперь создадим папку /tags в репозитории и для каждого тега создадим файл <имя тега>.md. В файле только начальная секция с именем тега:

---
layout: tagpage
tag: jekyll
---

Готово!

Теперь добавим на главную страницу облако тегов. Для этого отредактируем index.html, добавив в начало или в конец (как вам больше нравится) следующую секцию:

<p>
    {% for tag in site.tags %}
    <!-- Here's a hack to generate a "tag cloud" where the size of
    the word is directly proportional to the number of posts with
    that tag. -->
    <a href="/tags/{{ tag[0] }}/" 
    style="font-size: {{ tag[1] | size | times: 2 | plus: 10 }}px">
        {{ tag[0] }} | 
    </a>
    {% endfor %}
</p>

Исправляем баг с подсветкой кода

В умолчальном jekyll-now есть досадный баг: фреймы с кодом дублируются (один внутри другого). Решений этой проблемы несколько (например, тут).

В файле _sass/_highlights.scss измените строчку .highlight на pre.highlight. Также измените строчку overflow: scroll; на overflow: auto;, чтобы полосы прокрутки отображались, только если это необходимо.

Ставим git для Windows

Все указанные выше действия можно выполнить в интерфейсе GitHub, однако это не всегда удобно. Можно установить на компьютер Git и редактировать файлы в вашем любимом редакторе.

Вот отличный гайд с картинками на русском языке по установке и работе с Git и TortoiseGit.

Для Windows нам нужно установить сначала Git, потом TortoiseGit. После установки команды Git появятся в контекстном меню проводника.

Создайте папку для ваших исходников, откройте ее и кликните по пустому месту ПКМ. Выберите Git Clone…. В появившемся окне в поле URL скопируйте ссылку на ваш репозиторий и нажмите ОК. Вот где можно взять эту ссылку:

Файлы и репозитория склонируются в вашу папку.

Теперь, если вы внесли в какой-то файл или файлы изменения, то необходимо также кликнуть правой кнопкой в любом месте папки и нажать Git commit > master. Ввести краткое описание изменений и нажать Commit, а затем ПКМ > Tortoise Git > Push или Git Sync. Локальные изменения попадут в ваш репозиторий на GitHub.

Чтобы добавить новый файл в репозиторий, нужно кликнуть по нему или по пустому месту в репозитории и выбрать команду Add (или TortoiseGit > Add ). Затем также выполнить Commit и Push для загрузки файлов в удаленный репозиторий.

Стили

В стандартном jekyll-now не очень красивые таблицы. Чтобы это поправить нужно создать свой стиль. jekyll использует как обычный .css, так и продвинутый .scss. Добавим оформление таблиц как на GitHub.

В папке /_sass создадим файл _table.scss и скопируем туда стили GitHub для таблицы, например отсюда. Содержимое файла _table.css:

table {
  padding: 0; }
  table tr {
    border-top: 1px solid #cccccc;
    background-color: white;
    margin: 0;
    padding: 0; }
    table tr:nth-child(2n) {
      background-color: #f8f8f8; }
    table tr th {
      font-weight: bold;
      border: 1px solid #cccccc;
      text-align: left;
      margin: 0;
      padding: 6px 13px; }
    table tr td {
      border: 1px solid #cccccc;
      text-align: left;
      margin: 0;
      padding: 6px 13px; }
    table tr th :first-child, table tr td :first-child {
      margin-top: 0; }
    table tr th :last-child, table tr td :last-child {
      margin-bottom: 0; }

В файл style.scss в корне репозитория добавим строку в начало или конец файла:

@import "table";

Стили на GitHub кэшируются, поэтому их обновление может занять до 2-3 ч.

Плагины

Для jekyll есть множество полезных плагинов, но к несчастью самые классные из них GitHub Pages не поддерживаются.

Вот список тех плагинов, которые GitHub Pages поддерживает. Чтобы подключить плагин, нужно отредактировать файл _config.yml, добавив в него секцию plugins: со списком нужных плагинов, например:

plugins:
 - jekyll-feed
 - jekyll-redirect-from
 - jekyll-seo-tag
 - jekyll-sitemap
 - jekyll-avatar
 - jemoji
 - jekyll-mentions
 - jekyll-include-cache

Интересные статьи:

Метки: ,

Разделы:

Дата изменения:

Вам также может понравиться

Запись и рендеринг терминала

8 мин на чтение

Наверняка, вы видели в репозиториях GitHub README с анимацией консоли. Честно говоря до недавнего времени их назначение, кроме как “вау, красиво” было мне не...

Единый источник и CI-CD для Gostdown

24 мин на чтение

Gostdown - замечательный проект для нас, несчастных, крепко завязанных на Microsoft Word. И все же в основной версии кое-чего важного ему не хватает: трушног...