¹ Eсли только это не файлы внутренних страниц, типа этой.

Джекил сгенерирует статику из .md файла, который необходимо поместить в папку _posts/ . Для файлов существует строгая нотация именования ¹. Присутствует дата. Все буквы строчные.

Вся графика используемая в посте помещается в одноимённую папку внутри assets-orig/posts_data/.

├─ ...
├─ _drafts           #Drafts published only with jekyll serve --drafts
├─ _pages            #Inner pages like index, 404 etc
├─ _posts            #All posts goes here
│   ├─ articles
│   └─ projects
│       └─ 2015-03-28-testing-journey.md
├─ assets-orig
│   └─ posts_data    #Pictures for posts
│       └─ 2015-03-28-testing-journey
│           └─ tropical-island.png
├─ ...

Yaml для метаданных (Front Matter)

В начале каждого .md файла содержатся метаданные о посте, которые помогают Джекилу правильно сгенерировать пермалинки, расставить теги и категории. В нормальном случае мета выглядит так:

---
layout: post
category: articles
title: Большое тестовое приключение
description: Тестирование Джекила не может быть простым процессом, по позможности старайтесь избегать такого
date: 2016-12-20
updated: 2020-01-09
tags: [ Котики, Смерть, Здравомыслие ]
assets: /assets/posts_data/2016-12-20-cheatsheet
background: /assets/posts_data/2015-03-28-title-back-1920x490.jpg
share-snippet: "Тут команда «Насос Краб Педаль Кебаб» делает видеозвонки с гифками и занимает 3 место на тематическом хакатоне Ростелекома"
share-img: /assets/posts_data/2020-05-08-virushack-2020/share-1280x707.jpg
---

• layout — html-шаблон, который применится к посту во время генерации статики. Все шаблоны лежат в папке /_layouts
• updated — дата последних модификаций поста. Устанавливается вручную. Доступана во всплывающей подсказке.
• assets — папка со всеми ассетами поста. Используется как переменная для сокращения путей.
• background — ссылка на картинку для шапки поста. Все картинки хранятся в /assets и тоже имеют формат имени.
• share-snippet — текстовый сниппет который будет выводиться в превью страницы при шеринге. Работает на стандарте OpenGraph.
• share-img — картинка превью, которая будет выводиться при шеринге. 1200x630 и больше
• no-breadcrumbs — отключает шапку с крошками. Экспериментальный, опциональный тег с булевыми значениями.
• language — Экспериментальный, опциональный тег, который отключает перевод месяцев в шапке поста. RU или EN.

Переменные

Можно использовать множество готовых переменных, или создавать свои.

• {{ site.icons }} — путь к векторным иконпакам сайта. Указан в _config.yml
• {{ site.url }} — url сайта забирается из config.yml.
• {{ page.assets }} — путь к ассетам конкретного поста. Указан в мете самого поста.
• {{ page.url }} — url страницы. Удобно ссылаться на якоря.

Liquid тэги

У сайта много кастомных liquid тэгов. Большинство из них используются как алиасы для HTML кода, другие — по-настоящему упрощают жизнь. Благодаря тегам, исходники постов совсем не используют HTML кроме исключительных случаев. Все кастомные теги хранятся в папке _plugins.

# Sidebar notes with inline markdown and tags
{% sidebar %}
    [![this is alt of img]({{ page.assets }}/2015-03-28-title-back-1920x490.jpg)](https://ya.ru)
    {% nrs %}And there is short description of above pic in sidebar [with a link](https://ya.ru).
{% endsidebar %}

# Slider picture gallery with captions
{% slider %}
    bash-vs-zsh-1.png | Alt text for pic1 | Caption for the pic1
    bash-vs-zsh-2.png | Alt text for pic2 | Caption for the pic2 | optional max-height in px for vertical pics
    bash-vs-zsh-3.png | Alt text for pic3 | Caption for the pic3
{% endslider %}

# Single img with caption
{% imgc picture.jpg | img alt tag | Awesome caption %}

# Image at the very bottom will scale to height = 100
{% imgend picture.jpg | img alt tag | href url %}

# Related post at the very bottom of page
{% relposts %}
    Это ↑ заметка о том как работает этот сайт. Вот остальные:
    [Подсказки о том как жить]({{site.url}}/pages/cheatsheet/)
    [Как сделать визу на Тайвань и не умереть]({{site.url}}/articles/taiwan/)
{% endrelposts %}

# Autonumbering for post notes
{% nr %} — numbered ref. Create SUP number by hash ID.
{% nrs %} — numbered ref in sidebar. Create same sup number for using in sidebar note.

# Alias content-align-... class with pre-adjusted width control (three, five, seven, ten):
{% left three | ![Funny panda]({{page.assets}}/funny_panda.jpg)  | Optional gray description text %}
{% center five | ![Funny panda]({{page.assets}}/funny_panda.jpg) %}
{% right seven | ![Funny panda]({{page.assets}}/funny_panda.jpg) %}

# Mobile-specific snippet with TEXT ONLY, SYMBOL or EMOJI, IMAGE or ICON
{% mobiletext Some text with [md markup](http://ya.ru) %}
{% mobilesymtext ★ | Some text with [md markup](http://ya.ru) %}
{% mobileimgtext pic.jpg | Alt text | Some text with [md markup](http://ya.ru) %}
{% mobileicontext /flat-files/pdf.svg | Some text with [md markup](http://ya.ru) %}

# Local video HTML5 tag. Suitable for looped gifs substitution
{% video gif-like | kipo.mp4 | Optional caption %}

# Youtube iframe html code include
{% youtube pdnCXuYcNBg?start=70 %}

# Vimeo iframe html code include
{% vimeo 22439234 %}

# Coub iframe to the sidebar
{% coubside 14frey %}

# Collapsible spoilers across content
{% spoiler Spoiler inside! %}
Super creepy spoiler with [markdown](#) support
{% endspoiler %}

# Normalized text decoration
# {% norm 🥸 %}

Markdown для всего остального

Маркдаун — основная разметка для всех контентных страниц. В качестве основного парсера Джекил использует Kramdown.

Заголовки

# 1. Это главный заголовок первого уровня — H1
## 2. Самый используемый заголовок второго уровня
### 3. H3 — третий уровень заголовков. Тоже в ходу.
#### 4. Заголовком H4, думаю, никто никогда пользоваться не будет

Выделения

- Наклонный шрифт можно получить одинарными *звёздочками* или _подчёркиваниями_.
- Жирное начертание, болд с двойными **звёздочками** или __подчёркиваниями__.
- Комбинированный вариант со **звёздочками и _подчеркиваниями_**.
- А двумя тильдами можно всё зачеркнуть ~~Удалите это~~

↓

• Наклонный шрифт можно получить одинарными звёздочками или подчёркиваниями.
• Жирное начертание, болд с двойными звёздочками или подчёркиваниями.
• Комбинированный вариант со звёздочками и подчеркиваниями.
• А двумя тильдами можно всё зачеркнуть Удалите это

Списки

1. Первый пункт нумерованного списка
2. Второй пункт
  * Вложенный пункт второго уровня отбит двумя пробелами
1. Нет разницы какой будет цифра, если список продолжается, то она будет исправлена.
  1. Нумерованный вложенный список второго уровня. Отбит двумя пробелами
4. Последний пункт нумерованного списка.

   А ещё можно расставлять абзацы внутри спиков и это работает прекрасно. Главное отбить этот абзац пробельной строкой и потом выровнять его пробелами по контенту списка. В данном случае используется три пробела от начала строки.

   Абсолютно контринтуитивная хрень — это разрыв строки при помощи двойного пробела в её конце.
   Обратите внимание, как эта строка начинается заново при этом находится в параграфе и не использует пробельную строку вначале.
   В теории такое поведение никак не пересекается с правилами GFM, но почему-то работает.

* Маркированный список можно построить на звёздочках
- Минусах
+ Или даже плюсах

↓

1. Первый пункт нумерованного списка
2. Второй пункт
   • Вложенный пункт второго уровня отбит двумя пробелами
3. Нет разницы какой будет цифра, если список продолжается, то она будет исправлена.
4. Нумерованный вложенный список второго уровня. Отбит двумя пробелами

5. Последний пункт нумерованного списка.

   А ещё можно расставлять абзацы внутри спиков и это работает прекрасно. Главное отбить этот абзац пробельной строкой и потом выровнять его пробелами по контенту списка. В данном случае используется три пробела от начла строки.

   Абсолютно контринтуитивная хрень — это разрыв строки при помощи двойного пробела в её конце. Обратите внимание, как эта строка начинается заново при этом находится в параграфе и не использует пробельную строку вначале. В теории такое поведение никак не пересекается с правилами GFM, но почему-то работает.

• Маркированный список можно построить на звёздочках
• Минусах
• Или даже плюсах

Ссылки

- [Типичная инлайн-ссылка](https://www.snnkv.com)
- [Инлайн-ссылка с тайтлом](https://www.snnkv.com "Сайт Санникова")
- [Относительная ссылка](/assets/posts_data/2016-12-20-cheatsheet/2016-12-20-cheatsheet-title-1920x490.jpg)
- [Референсная ссылка с номером][1]

Но вот это самый «сухой» [пример референса].

Урлы в треугольных скобках будут автоматически порендерены как ссылки, как, например <http://www.example.com>

Обычно все референсные ссылки ставятся в конце текста. Так их проще искать и редактировать. Разумеется в тексте эти ссыки рендериться не будут.

[1]: http://www.snnkv.com
[пример референса]: http://www.snnkv.com

↓

• Типичная инлайн-ссылка
• Инлайн-ссылка с тайтлом
• Относительная ссылка
• Референсная ссылка с номером

Но вот это самый «сухой» пример референса.

Урлы в треугольных скобках будут автоматически порендерены как ссылки, как, например http://www.example.com

Картинки

Все картинки вставленные через регулярные маркдаун-теги будут занимать всю ширину контентного блока.

Инлайн:
![alt text](http://satyr.io/632x10/1 "Тайтл для картинки")

Референс:
![alt text][satyrio]

[satyrio]: http://satyr.io/632x10/2 "Тайтл для второй картинки"

↓

Инлайн:

Референс:

Подсветка синтаксиса

Для подсветки синтаксиса используется Rouge.

код можно `highlight` инлайн при помощи апострофов и `it works` просто фантастически.

↓

код можно highlight инлайн при помощи апострофов и it works просто фантастически.

Можно вставлять целыми блоками, указав предварительно язык содержимого:

    ```css
    img {
        color: transparent;
        font-size: 0;
        vertical-align: middle;
        -ms-interpolation-mode: bicubic
    }
    ```

    ```python
    s = "Python syntax highlighting"
    print s
    ```

    ```
    Язык не указан, поэтому по умолчанию выбран markdown и ничего не подсвечено.
    But let's throw in a <b>tag</b>.
    ```

↓

img {
    color: transparent;
    font-size: 0;
    vertical-align: middle;
    -ms-interpolation-mode: bicubic
}

s = "Python syntax highlighting"
print s

Язык не указан, поэтому по умолчанию выбран markdown и ничего не подсвечено.
But let's throw in a <b>tag</b>.

Таблицы

Вообще таблицы не являются частью спецификации Маркдауна, но практически любой современный парсер их поддерживает.

Двоеточия используются для выравнивания контента колонки

| Ингридиент        | Объём              | Цена  |
| ----------------- |:------------------:| -----:|
| Капуста           | Средний велок      | $1.60 |
| Картошка          | 1 кг.в сетке       | $0.90 |
| Свекла            | 3 шт. в блистере   | $12.0 |

1. Для выделения шапки таблицы во второй строке должно быть минимум 3 минуса.
1. Внешние «стенки» (|) таблицы необязательны.
1. Выравнивание всего по сетке необязательно.
1. В мобильной версии широкие таблицы имеют горизонтальный скролл.
1. Внутри таблиц работает выделение:

Markdown | Less | Pretty
--- | --- | ---
*Still* | `renders` | **nicely**
1 | 😵 | 3

↓

Двоеточия используются для выравнивания контента колонки

1. Для выделения шапки таблицы во второй строке должно быть минимум 3 минуса.
2. Внешние «стенки» | таблицы необязательны.
3. Выравнивание всего по сетке необязательно.
4. В мобильной версии широкие таблицы имеют горизонтальный скролл.
5. Внутри таблиц работает выделение:

Цитаты

> В цитаты превращается любой текст после треугольной скобки.
> Это продолжение первой строчки.

Цитаты отбиваются от остально контента пробельной строкой сверху и снизу

> Инлайн-цитата в виде одной единственной длинной строки.

↓

В цитаты превращается любой текст после треугольной скобки. Это продолжение первой строчки.

Футноты

Оказалось Kramdown и Джекилл умеют работать с футнотами выполненными в формате [^1]. Это не поддерживается стилями этого сайта, однако работает и может пригодиться в будущем.

Table of content

Ещё Kramdown и Джекилл умеют автоматически формировать содерджание поста с активными ссылками на подзаголровки. Для этого можно использовать одиночный тег {:toc}, но сразу до, или после него необходимо сидировать формат списка.

- Seeding unordered list
{:toc}

Горизонтальная черта

Больше трёх минусов

-----

или Звёздочек подряд

*********

Рисуют длинную горизонтальную полосу на всю ширину контентного блока + сайдбар.

↓

Эскейпинг

Можно запретить парсеру преобразовывать теги

Новая строка без нового параграфа

Для этого лишь нужно поставить \ в конце строки. Полный аналог html-тега <br/>

HTML для странного

Не все элементы страницы получается расставить при помощи маркдауна. В исключительных ситуациях приходится использовать HTML. Этот раздел приведён, скорее, для справки и показывает актуальное состояние кода, который потом используется в liquid тэгах.

Картинка на всю ширину контентного блока

Есть возможность заверстать картинку на всю ширину контентного болока и сделать к ней подпись. Если подпись не нужна, то можно использовать кусок без <div class="description">:

<div class="full-width">
    <img loading="lazy"
        src="http://placehold.it/960x520&text=full-width+image"
        alt="alt text for picture">
    <div class="description">
        Lorem ipsum, dolor sit amet consectetur adipisicing elit.
    </div>
</div>

Получится вот так:

Lorem ipsum, dolor sit amet consectetur adipisicing elit. Earum ut facere recusandae deleniti quae corporis quos maxime incidunt?

Именно этот html код реализован через тег imgc. В обычном случае через маркдаун картинка будет вставлена на 75% ширины (см. ниже).

Галереи картинок

Для галерей используется Swiper, который пришёл на смену старой Slick Gallery. Для каждой картинки можно указать подпись.

<!-- Slider main container -->
<div class="swiper">
    <!-- Additional required wrapper -->
    <div class="swiper-wrapper">
        <!-- Slides -->
        <div class="swiper-slide">
            <div class="swiper-slide-image-wrapper">
                <img class="swiper-slide-image" src="http://satyr.io/1920x1200/1" loading="lazy" alt="1">
                <div class="swiper-lazy-preloader swiper-lazy-preloader-white"></div>
            </div>
            <div class="swiper-slide-description">Один из вариантов того, к чему мы стремились</div>
        </div>
        <div class="swiper-slide">
            <div class="swiper-slide-image-wrapper">
                <img class="swiper-slide-image" src="http://satyr.io/500x900/2" loading="lazy" alt="second">
                <div class="swiper-lazy-preloader swiper-lazy-preloader-white"></div>
            </div>
            <div class="swiper-slide-description">Ешё один из вариантов того, к чему мы стремились</div>
        </div>
        <div class="swiper-slide">
            <div class="swiper-slide-image-wrapper">
                <img class="swiper-slide-image" src="http://satyr.io/1920x1080/3" loading="lazy" alt="some">
                <div class="swiper-lazy-preloader swiper-lazy-preloader-white"></div>
            </div>
            <div class="swiper-slide-description">К чему мы, в итоге пришли и для описания чего необходимо использовать чрезвычайно длинную строку, которая наверняка будет рендериться в два уровня, ведь её длина по-настоящему неадекватно. В ней даже используется два разных предложения.</div>
        </div>
    </div>
    <!-- If we need pagination -->
    <div class="swiper-pagination"></div>
    <!-- If we need navigation buttons -->
    <div class="swiper-button-prev"></div>
    <div class="swiper-button-next"></div>
</div>

В результате получится так:

Один из вариантов того, к чему мы стремились

Вертикальный вариант того, к чему мы стремились

К чему мы, в итоге пришли и для описания чего необходимо использовать чрезвычайно длинную строку, которая наверняка будет рендериться в два уровня, ведь её длина по-настоящему неадекватно. В ней даже используется два разных предложения.

Текст и сноски в сайдбаре

² Приблизительно такого. В нём даже можно использовать ссылки.

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

<p class="note"><sup>2</sup> Приблизительно такого. В нём даже можно <a href="http://www.snnkv.com">использовать ссылки</a>.</p>

Результат работы этого кода можно увидеть справа.

Сноски в сайдбаре не рендерятся в мобильной вёрсии

Любой контент в сайдбаре

Сайдбар имеет фиксированную ширину и в него можно поместить любой контент. Текст, графику, гифку, видео, или даже аудиоплеер. Сайдбар стерпит всё. Смотрите:

<p class="sidebar"><iframe width="168" height="110" src="https://www.youtube.com/embed/I53HDr0-Qew" frameborder="0" allowfullscreen></iframe></p>

Выравнивание контента

Для горизонтального выравнивания любого контента внутри основного блока и в сайдбаре есть несколько специальных классов.

<span class="content-align-left">Любой контент слева</span>
<span class="content-align-center">Любой контент по центру</span>
<span class="content-align-right">Любой контент справа</span>

Одновременно с этим можно установить максимальный размер получившегося блока через допольнительные классы three, five, seven, ten которые занимают соответственно 30%, 50%, 70% и 100% ширины контентного блока (без сайдбара), или гранулированно через <span style="max-width: 63%;">

Код может выглядеть так:

<span class="content-align-left three">Любой контент слева занимает 30%</span>
<span class="content-align-center" style="max-width: 82%;">Контент по центру занял 82% ширины</span>

Чаще всего выравниваются картинки и гифки. Для них можно организовать подпись, как тут:

Pornhub сделал премиум-подписку на месяц доступной для всех пользователей

Использованный код:

<span class="content-align-center five">
    <img src="https://leonardo.osnova.io/c34b71d3-c2cf-9b26-b98c-1fe617b57471/-/resize/1400/" alt="Pornhub">
    <br>
    <span class="description">Pornhub сделал премиум-подписку на месяц доступной для всех пользователей</span>
</span>

Локальное видео

На сайте работает HTML тег <video>. Им удобно заменить гифки. Для него есть отдельный liquid-тег, но в нормальном виде он выглядит так:

<span class="content-align-center ten">
    <video width="100%" height="100%" preload="metadata" autoplay loop muted>
        <source src="/assets/posts_data/2016-12-20-cheatsheet/kipo.mp4" type="video/mp4">
        Тут должно быть видео, но, кажется, ваш браузер — говно мамонта.
    </video>
    <br>
    <span class="description">Новый виток мема «Я и мой брат-дебил»</span>
</span>

Важно обратить внимание на два момента:

• Если нужно вставить проигрываемый видеоролик со звуком, в наборе атрибутов обязательно должен быть controls. В примере выше приведена gif-like вставка. Ролик будет сам бесконечно воспроизводиться без звука. Стартовать будет когда пользователь его увдит, а когда ролик не видим, будет устанавливаться на паузу.
• Из-за политик безопасности в MacOS во время тестирования такие файлы лучше оценивать из Safari т.к. операционка не даёт Хрому проигрывать с диска всё подряд. В Chrome во время локального тестирвоания это будет работать только в мобильном режиме. Не спрашивайте.

Блоки мобильной версии

Из-за того что мы не можем интегрировать сайдбар в мобильную версию, используем там специальные горизонтальные блоки-акценты. Эти блоки видны только в мобильной версии сайта.

Выглядеть могут так:

Сами блоки мы разделили на несколько однообразных типов:

<!-- Простой текст с поддержкой маркдауна -->
<p class="mobile-note" markdown="1">Особенный текст для [вашего](https://ya.ru) внимания</p>

<!-- Векторная иконка и текст с поддержкой маркдауна -->
<div class="mobile-note-pic clearfix">
    <div class="mobile-note-pic-image">
        <img src="/assets/icon-packs/flat-files/pdf.svg" alt="Alt text" height="50">
    </div>
    <div class="mobile-note-pic-desc">
        <p markdown="1">Особенный текст для [вашего](https://ya.ru) внимания</p>
    </div>
</div>

<!-- Картинка и текст с поддержкой маркдауна -->
<div class="mobile-note-pic clearfix">
    <div class="mobile-note-pic-image">
        <img src="/assets/posts_data/2016-12-20-cheatsheet/test.png" alt="Alt text">
    </div>
     <div class="mobile-note-pic-desc">
        <p markdown="1">Особенный текст для [вашего](https://ya.ru) внимания</p>
    </div>
</div>

<!-- Символ или эмодзи и текст с поддержкой маркдауна -->
<div class="mobile-note-pic clearfix">
    <div class="mobile-note-pic-image">
        🐟
    </div>
    <div class="mobile-note-pic-desc">
        <p markdown="1">Особенный текст для [вашего](https://ya.ru) внимания</p>
    </div>
</div>

Подножие с похожими постами

Ради возможности вручную подбирать и аннотировать промо-посты по теме используем инлайн-html:

<div class="additional">
    <h4>Это ↑ заметка из списка туториалов об этом сайте. Вот остальные:</h4>
    <div class="suggestions">
        <a href="/404">Тестирвоание 101</a>
        <br>
        <a href="/404">Прошлогодний пост</a>
        <br>
        <a href="javascript:void(0);">Большое тестовое приключение</a>
        <br>
        <a href="/404">Чрезвычайно старая заметка</a>
        <br>
    </div>
</div>

Результат есть в подножии этой страницы.

Раскрывающиеся блоки

В стандарте HTML5 есть тег позволяющий скрывать часть контента за сниппетом. Если хочется использовать Markdown внутри, то нужно будет избегать отступов-пробелов.

<details markdown="1">
<summary class="spoiler">Разверни меня</summary>
Этот тег неплохо комбится, например, с [Содержанием для заметок](/pages/cheatsheet/#table-of-content).
</details>

↓

Для использования обычно применяется class="spoiler", иначе всё будет отформатировано, как содержание. Для этого блока есть парный ликвид-тег.

Сторонние iframe

Любые инклюды с других сайтов, которые вставляются через <iframe> необходимо оборачитвать в <p> ... </p>.

Дополнительно

Тут всё, что не влезло, либо имеет минорное значение.