Пост

Написание новой статьи

Опубликовано
Preview Image
Автор Jakhongir Kakharov
просмотров 9 мин. чтения
Написание новой статьи

Это руководство покажет вам, как писать статьи в шаблоне Chirpy. Даже если вы раньше использовали Jekyll, стоит ознакомиться — для многих возможностей требуются специальные переменные.

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

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

Front Matter

В основном вам нужно заполнить следующий Front Matter в верхней части поста:

1
2
3
4
5
6

---
title: TITLE
date: YYYY-MM-DD HH:MM:SS +/-TTTT
categories: [TOP_CATEGORY, SUB_CATEGORY]
tags: [TAG]     # Имена тегов всегда должны быть в нижнем регистре
---

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

Дата и часовой пояс

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

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

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

1
2
3
4

---
categories: [Животные, Насекомые]
tags: [пчела]
---

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

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

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

1
2
3
4

<author_id>:
  name: <полное имя>
  twitter: <twitter автора>
  url: <веб-сайт автора>

Затем используйте author для одной записи или authors для нескольких:

1
2
3
4
5

---
author: <author_id>                     # для одного автора
# или
authors: [<author1_id>, <author2_id>]   # для нескольких авторов
---

Стоит отметить, что ключ author также может указывать на несколько записей.

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

Описание поста

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

1
2
3

---
description: Краткое содержание поста.
---

Также description будет показано под заголовком поста на странице самого поста.

Оглавление (TOC)

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

1
2
3

---
toc: false
---

Комментарии

Глобальная настройка комментариев задаётся через опцию comments.provider в файле _config.yml. После выбора провайдера комментариев комментарии включаются для всех постов.

Чтобы отключить комментарии для отдельного поста, добавьте в Front Matter:

1
2
3

---
comments: false
---

Медиа

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

Префикс URL

Иногда нужно задать повторяющийся префикс URL для нескольких ресурсов поста; это можно сделать с помощью параметров cdn и media_subpath.

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

    1

    cdn: https://cdn.com

  • Для задания префикса пути ресурсов для текущего поста/страницы установите media_subpath в front matter поста:

    1
2
3

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

Опции site.cdn и page.media_subpath могут работать отдельно или вместе, что даёт гибкость в формировании итогового URL: [site.cdn/][page.media_subpath/]file.ext

Изображения

Подпись

Добавьте курсивную строку сразу под изображением — это будет подпись, отображаемая под изображением:

1
2

![img-description](/path/to/image)
_Подпись изображения_

Размеры

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

1

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

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

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

1

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

Позиция

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

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

  • Обычная позиция

    В примере ниже изображение выровнено влево:

    1

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

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

    1

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

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

    1

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

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

Вы можете адаптировать изображения под тёмную/светлую тему: подготовьте два изображения — для тёмного и для светлого режима — и назначьте им специальные классы (dark или light):

1
2

![Только для светлой темы](/path/to/light-mode.png){: .light }
![Только для тёмной темы](/path/to/dark-mode.png){: .dark }

Тень

Скриншоты окон приложений можно снабдить эффектом тени:

1

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

Превью изображения (опен-грaф/preview)

Если вы хотите добавить изображение в верхнюю часть поста (preview), предоставьте изображение размером 1200 x 630. Если соотношение сторон не совпадает с 1.91 : 1, изображение будет масштабировано и обрезано.

Зная это, вы можете настроить атрибуты изображения в Front Matter:

1
2
3
4
5

---
image:
  path: /path/to/image
  alt: альтернативный текст изображения
---

Учтите, что [media_subpath](#url-prefix) также применим к preview-изображениям: когда он задан, path может содержать только имя файла изображения.

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

1
2
3

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

LQIP

Для preview-изображений:

1
2
3
4

---
image:
  lqip: /path/to/lqip-file # или base64 URI \"[Text and Typography](../text-and-typography/)\"
---

Вы можете увидеть LQIP в превью поста “Текст и типографика”.

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

1

![Описание изображения](/path/to/image){: lqip="/path/to/lqip-file" }

Видео

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

Вы можете встраивать видео с платформ с помощью следующего синтаксиса:

1

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

Здесь Platform — название платформы в нижнем регистре, а ID — идентификатор видео.

В таблице ниже показано, как извлечь нужные параметры из URL видео, а также перечислены поддерживаемые платформы.

Video URLПлатформаID
https://www.youtube.com/watch?v=H-B46URT4mgyoutubeH-B46URT4mg
https://www.twitch.tv/videos/1634779211twitch1634779211
https://www.bilibili.com/video/BV1Q44y1B7WfbilibiliBV1Q44y1B7Wf

Видеофайлы

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

1

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

Здесь URL — путь к видео, например /path/to/sample/video.mp4.

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

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

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

1
2
3
4
5
6
7
8
9
10

{%
  include embed/video.html
  src='/path/to/video.mp4'
  types='ogg|mov'
  poster='poster.png'
  title='Демо видео'
  autoplay=true
  loop=true
  muted=true
%}

Аудиофайлы

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

1

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

Здесь URL — путь к аудиофайлу, например /path/to/audio.mp3.

Для аудио также доступны дополнительные атрибуты:

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

Пример с полным набором атрибутов:

1
2
3
4
5
6

{%
  include embed/audio.html
  src='/path/to/audio.mp3'
  types='ogg|wav|aac'
  title='Демо аудио'
%}

Закреплённые посты

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

1
2
3

---
pin: true
---

Указания (prompts)

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

1
2

> Пример строки для указания.
{: .prompt-info }

Синтаксис

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

1

`inline код`

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

1

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

Кодовый блок

Markdown-блоки, создаваемые с помощью ``` позволяют легко вставлять фрагменты кода:

1
2
3

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

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

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

1
2
3

```yaml
key: value
```

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

Нумерация строк

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

1
2
3
4

```shell
echo 'Никакой нумерации строк!'
```
{: .nolineno }

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

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

1
2
3
4

```shell
# content
```
{: file="path/to/file" }

Код в Liquid в Front Matter

Параметр render_with_liquid: false отключает обработку Liquid-шаблонов Jekyll для этого файла. Это означает, что любые Liquid-теги ({{ }}, {% %}) или другая синтаксис Liquid не будут выполнены и останутся как обычный текст. Это полезно, когда нужно показать код Liquid или избежать его обработки.

Отображение кода Liquid

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

1
2
3
4
5
6
7

{% raw %}
```liquid
{% if product.title contains 'Pack' %}
  This product's title contains the word Pack.
{% endif %}
```
{% endraw %}

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

Математика

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

1
2
3

---
math: true
---

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

  • Блочная математика должна быть взята в $$ math $$; перед и после блока $$ обязательна пустая строка.
    • Нумерование уравнений: используйте $$\begin{equation} math \end{equation}$$.
    • Ссылка на номер уравнения: добавьте в блок \label{eq:label_name} и ссылку в тексте \eqref{eq:label_name} (см. пример ниже).
  • Inline-математика (в строке) тоже оборачивается в $$ math $$, но без пустых строк перед и после.
  • Inline-математика в списках: первый $ нужно экранировать.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

<!-- Блочная математика: сохраните все пустые строки -->

$$
LaTeX_math_expression
$$

<!-- Нумерация уравнения: сохраните все пустые строки  -->

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

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

<!-- Inline-математика в строках, без пустых строк -->

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

<!-- Inline-математика в списках, экранируйте первый `$` -->

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

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

Mermaid

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

1
2
3

---
mermaid: true
---

Дальше используйте его как любой другой язык разметки: оборачивайте код диаграммы в ```mermaid и ```.

Дополнительная информация

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

Blog, Обучение
Chirpy
Авторский пост защищен лицензией CC BY 4.0 .