Написание нового поста

В этом руководстве вы узнаете, как написать сообщение в шаблоне Chirpy, и его стоит прочитать, даже если вы раньше использовали Jekyll, поскольку многие функции требуют установки определенных переменных.

Именование и путь

Создайте новый файл с именем YYYY-MM-DD-TITLE.EXTENSION и ​​поместите его в _posts корневого каталога. Обратите внимание, что EXTENSION должен быть одним из md и ​​markdown. Если вы хотите сэкономить время на создании файлов, рассмотрите возможность использования для этого плагина Jekyll-Compose.

Фронт-маттер

Вам нужно заполнить Front Matter в начале поста:

---
title: TITLE
date: YYYY-MM-DD HH:MM:SS +/-TTTT
categories: [TOP_CATEGORY, SUB_CATEGORY]
tags: [TAG]     # TAG names should always be lowercase
---

По умолчанию для постов установлено значение post, поэтому нет необходимости добавлять переменную layout в блок Front Matter.

Часовой пояс даты

Чтобы корректно указать дату публикации, задайте timezone в _config.yml и укажите смещение часового пояса в date фронт-маттера. Формат: +/-TTTT, например +0800.

Категории и теги

categories каждого поста могут содержать до двух элементов, а количество элементов в tags может быть от нуля до бесконечности. Например:

---
categories: [Animal, Insect]
tags: [bee]
---

Информация об авторе

Информацию об авторе обычно не нужно задавать в Front Matter: по умолчанию она берется из social.name и первой записи social.links в конфигурации. При необходимости это можно переопределить:

Добавление информации об авторе в _data/authors.yml (если на вашем сайте нет этого файла, не стесняйтесь создать его).

<author_id>:
  name: <full name>
  twitter: <twitter_of_author>
  url: <homepage_of_author>

Затем используйте author, чтобы указать одну запись, или authors, чтобы указать несколько записей:

---
author: <author_id>                     # for single entry
# or
authors: [<author1_id>, <author2_id>]   # for multiple entries
---

При этом ключ author также может идентифицировать несколько записей.

Преимущество чтения информации об авторе из файла _data/authors.yml состоит в том, что страница будет иметь метатег twitter:creator, который выполняет Twitter Cards и используется для SEO.

Описание сообщения

По умолчанию первые слова сообщения используются для отображения на домашней странице со списком сообщений, в блоке Further Reading и в XML-канале RSS. Если вы не хотите отображать автоматически созданное описание публикации, вы можете настроить его с помощью поля description в Front Matter следующим образом:

---
description: Short summary of the post.
---

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

Оглавление

По умолчанию оглавление (TOC) отображается в правой панели поста. Чтобы отключить его глобально, установите toc: false в _config.yml. Чтобы отключить TOC только для одного поста, добавьте в его Front Matter следующее:

---
toc: false
---

Комментарии

Глобальные настройки комментариев определяются опцией comments.provider в файле _config.yml. Как только для этой переменной будет выбрана система комментариев, комментарии будут включены для всех сообщений.

Если вы хотите закрыть комментарий к определенному сообщению, добавьте следующее в Front Matter сообщения:

---
comments: false
---

СМИ

Мы называем изображения, аудио и видео медиаресурсами в Chirpy.

Префикс URL-адреса

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

• Если вы используете CDN для размещения медиафайлов, вы можете указать cdn в _config.yml. URL-адреса медиа-ресурсов для аватара сайта и сообщений затем начинаются с имени домена CDN.

  cdn: https://cdn.com
  

• Чтобы указать префикс пути к ресурсу для текущей записи/диапазона страниц, установите media_subpath во Front Matter публикации:

  ---
  media_subpath: /path/to/media/
  ---
  

Варианты site.cdn и page.media_subpath можно использовать по отдельности или вместе для гибкого формирования конечного ресурса URL-адреса: [site.cdn/][page.media_subpath/]file.ext

Изображения

Подпись

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

![img-description](/path/to/image)
_Image Caption_

Размер

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

![Desktop View](/assets/img/sample/mockup.png){: width="700" height="400" }

Для SVG вам необходимо как минимум указать его ширину, иначе он не будет отображен.

Начиная с Chirpy v5.0.0, height и width поддерживают сокращения (height → h, width → w). Следующий пример имеет тот же эффект, что и приведенный выше:

![Desktop View](/assets/img/sample/mockup.png){: w="700" h="400" }

Позиция

По умолчанию изображение центрировано, но вы можете указать положение, используя один из классов normal, left и right.

После указания позиции подпись к изображению добавлять не следует.

• Нормальное положение

  Изображение будет выровнено по левому краю в примере ниже:

  ![Desktop View](/assets/img/sample/mockup.png){: .normal }
  

• Плавать влево

  ![Desktop View](/assets/img/sample/mockup.png){: .left }
  

• Плавать вправо

  ![Desktop View](/assets/img/sample/mockup.png){: .right }
  

Темный/Светлый режим

Вы можете настроить изображения в соответствии с настройками темы в темном/светлом режиме. Для этого необходимо подготовить два изображения: одно для темного режима и одно для светлого, а затем назначить им определенный класс (dark или light):

![Light mode only](/path/to/light-mode.png){: .light }
![Dark mode only](/path/to/dark-mode.png){: .dark }

Тень

Скриншоты окна программы можно считать демонстрирующими эффект тени:

![Desktop View](/assets/img/sample/mockup.png){: .shadow }

Предварительный просмотр изображения

Если вы хотите добавить изображение вверху публикации, предоставьте изображение с разрешением 1200 x 630. Обратите внимание: если соотношение сторон изображения не соответствует 1.91 : 1, изображение будет масштабировано и обрезано.

Зная эти предварительные условия, вы можете приступить к настройке атрибута изображения:

---
image:
  path: /path/to/image
  alt: image alternative text
---

Обратите внимание, что media_subpath также можно передать в изображение предварительного просмотра, то есть, если он установлен, атрибуту path требуется только имя файла изображения.

Для простоты использования вы также можете просто использовать image для определения пути.

---
image: /path/to/image
---

LQIP

Для изображений предварительного просмотра:

---
image:
  lqip: /path/to/lqip-file # or base64 URI
---

Вы можете увидеть LQIP на превью поста «Text and Typography».

Для обычных изображений:

![Image description](/path/to/image){: lqip="/path/to/lqip-file" }

Платформы социальных сетей

Вы можете вставлять видео/аудио с платформ социальных сетей, используя следующий синтаксис:

{% include embed/{Platform}.html id='{ID}' %}

Где Platform — это строчная буква названия платформы, а ID — идентификатор видео.

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

URL-адрес видео	Платформа	ИДЕНТИФИКАТОР
https://www.youtube.com/watch?v=H-B46URT4mg	youtube	H-B46URT4mg
https://www.twitch.tv/videos/1634779211	twitch	1634779211
https://www.bilibili.com/video/BV1Q44y1B7Wf	bilibili	BV1Q44y1B7Wf
https://www.open.spotify.com/track/3OuMIIFP5TxM8tLXMWYPGV	spotify	3OuMIIFP5TxM8tLXMWYPGV

Spotify поддерживает некоторые дополнительные параметры:

• compact - ​​вместо этого отображать компактный плеер (напр. {% include embed/spotify.html id='3OuMIIFP5TxM8tLXMWYPGV' compact=1 %});
• dark - ​​включить темную тему (например, {% include embed/spotify.html id='3OuMIIFP5TxM8tLXMWYPGV' dark=1 %}).

Видео файлы

Если вы хотите встроить видеофайл напрямую, используйте следующий синтаксис:

{% include embed/video.html src='{URL}' %}

Где URL – это URL-адрес видеофайла, например. /path/to/sample/video.mp4.

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

• poster='/path/to/poster.png' — изображение постера к видео, которое отображается во время загрузки видео.
• title='Text' — заголовок видео, который отображается под видео и выглядит так же, как для изображений.
• autoplay=true — видео автоматически начинает воспроизведение, как только это возможно.
• loop=true — автоматический возврат к началу при достижении конца видео.
• muted=true — изначально звук будет отключен
• types — укажите расширения дополнительных видеоформатов, разделенных знаком |. Убедитесь, что эти файлы находятся в том же каталоге, что и ваш основной видеофайл.

Рассмотрим пример, использующий все вышеперечисленное:

{%
  include embed/video.html
  src='/path/to/video.mp4'
  types='ogg|mov'
  poster='poster.png'
  title='Demo video'
  autoplay=true
  loop=true
  muted=true
%}

Аудио файлы

Если вы хотите встроить аудиофайл напрямую, используйте следующий синтаксис:

{% include embed/audio.html src='{URL}' %}

Где URL – это URL-адрес аудиофайла, например. /path/to/audio.mp3.

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

• title='Text' — заголовок аудио, который отображается под аудио и выглядит так же, как для изображений.
• types — укажите расширения дополнительных аудиоформатов, разделенных |. Убедитесь, что эти файлы находятся в том же каталоге, что и ваш основной аудиофайл.

Рассмотрим пример, использующий все вышеперечисленное:

{%
  include embed/audio.html
  src='/path/to/audio.mp3'
  types='ogg|wav|aac'
  title='Demo audio'
%}

Закрепленные сообщения

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

---
pin: true
---

Подсказки

Существует несколько типов подсказок: tip, info, warning и danger. Их можно создать, добавив в цитату класс prompt-{type}. Например, определите подсказку типа info следующим образом:

> Example line for prompt.
{: .prompt-info }

Синтаксис

Встроенный код

`inline code part`

Выделение пути к файлу

`/path/to/a/file.extend`{: .filepath}

Кодовый блок

Символы уценки ``` могут легко создать блок кода следующим образом:

```
Это фрагмент кода в виде открытого текста.
```

Указание языка

Используя ```{language}, вы получите блок кода с подсветкой синтаксиса:

```yaml
ключ: значение
```

Тег Jekyll {% highlight %} несовместим с этой темой.

Номер строки

По умолчанию на всех языках, кроме plaintext, console и terminal, отображаются номера строк. Если вы хотите скрыть номер строки блока кода, добавьте к нему класс nolineno:

```shell
echo 'Больше никаких номеров строк!'
```
{: .nolineno }

Указание имени файла

Возможно, вы заметили, что язык кода будет отображаться в верхней части блока кода. Если вы хотите заменить его именем файла, вы можете добавить атрибут file для достижения этой цели:

```shell
# содержание
```
{: file="path/to/file" }

Жидкие коды

Если вы хотите отобразить фрагмент Liquid, окружите код жидкости {% raw %} и {% endraw %}:

{% raw %}
```liquid
{% if product.title contains 'Pack' %}
  В названии этого продукта содержится слово Pack.
{% endif %}
```
{% endraw %}

Или добавьте render_with_liquid: false (требуется Jekyll 4.0 или выше) в блок YAML сообщения.

Математика

Мы используем [MathJax][mathjax] для генерации математических вычислений. Из соображений производительности веб-сайта математическая функция по умолчанию не загружается. Но его можно включить:

---
math: true
---

После включения математической функции вы можете добавлять математические уравнения со следующим синтаксисом:

• Математические блоки следует добавлять с помощью $$ math $$ с обязательными пустыми строками до и после $$.
  • Нумерацию уравнений следует добавлять с помощью $$\begin{equation} math \end{equation}$$
  • Нумерацию уравнений следует выполнять с помощью \label{eq:label_name} в блоке уравнений и \eqref{eq:label_name} в тексте (см. пример ниже).
• Встроенные математические выражения (в строках) следует добавлять с помощью $$ math $$ без каких-либо пустых строк до или после $$.
• Встроенные математические вычисления (в списках) следует добавлять с помощью \$$ math $$.

<!-- Block math, keep all blank lines -->

$$
LaTeX_math_expression
$$

<!-- Equation numbering, keep all blank lines  -->

$$
\begin{equation}
  LaTeX_math_expression
  \label{eq:label_name}
\end{equation}
$$

Can be referenced as \eqref{eq:label_name}.

<!-- Inline math in lines, NO blank lines -->

"Lorem ipsum dolor sit amet, $$ LaTeX_math_expression $$ consectetur adipiscing elit."

<!-- Inline math in lists, escape the first `$` -->

1. \$$ LaTeX_math_expression $$
2. \$$ LaTeX_math_expression $$
3. \$$ LaTeX_math_expression $$

Начиная с v7.0.0, параметры конфигурации MathJax были перенесены в файл assets/js/data/mathjax.js, и вы можете изменять параметры по мере необходимости, например добавляя расширения. Если вы создаете сайт с помощью chirpy-starter, скопируйте этот файл из каталога установки драгоценного камня (проверьте командой bundle info --path jekyll-theme-chirpy) в тот же каталог вашего репозитория.

Русалка

Mermaid — отличный инструмент для создания диаграмм. Чтобы включить его в своем сообщении, добавьте в блок YAML следующее:

---
mermaid: true
---

Затем вы можете использовать его, как и другие языки уценки: окружите код графа ```mermaid and ```.

Узнать больше

Для получения дополнительной информации о сообщениях Джекилла посетитель Jekyll Docs: Posts.