Post

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

Posted Updated
By Cotes Chung
8 min read
Написание нового поста

Это руководство описывает, как написать пост в шаблоне Chirpy. Его стоит прочитать, даже если вы знаете Jekyll, так как многие возможности зависят от определённых переменных.

Написание с помощью dumalog

dumalog dumalog

Не хотите возиться с шаблоном? dumalog — это ИИ-агент, который превращает ваши рабочие переписки (Claude Code, Codex CLI) в готовые к публикации посты Jekyll. Он хранит историю чатов локально в индексе memPalace и создаёт черновики с правильным фронт-маттером — включая поля language / translation_key темы NLO, — так что черновик сразу готов к публикации.

1
2
3

curl -fsSL https://raw.githubusercontent.com/GoXLd/dumalog/main/install.sh | bash
dumalog setup            # найти блог и изучить его стиль
dumalog write "тема"     # создать черновик (без темы — предложит варианты)

Всё работает локально; модели отправляется только анонимизированный контекст, нужный для черновика. Остальная часть руководства описывает фронт-маттер и Markdown, которые dumalog заполняет за вас, — полезно, когда черновик нужно доработать вручную.

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

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

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

Заполните 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]     # TAG names should always be lowercase
---

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

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

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

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

Пост принимает до двух categories и любое количество tags. Например:

1
2
3
4

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

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

Информацию об авторе обычно не нужно задавать в Front Matter: по умолчанию она берётся из social.name и первой записи social.links в конфигурации. Чтобы переопределить её, добавьте автора в _data/authors.yml (создайте файл, если его нет):

1
2
3
4

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

Затем укажите одну запись через author или несколько через authors:

1
2
3
4
5

---
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 и в RSS. Чтобы заменить этот автоматический фрагмент, задайте поле description в Front Matter:

1
2
3

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

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

Оглавление

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

1
2
3

---
toc: false
---

Комментарии

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

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

1
2
3

---
comments: false
---

Медиа

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

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

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

  • Если медиафайлы размещены в 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)
_Image Caption_

Размер

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

1

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

Для SVG нужно указать хотя бы ширину, иначе он не отобразится.

Начиная с Chirpy v5.0.0, height и width можно сокращать (h, 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

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

Тень

Скриншоты окон программ можно показать с эффектом тени:

1

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

Изображение для предпросмотра

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

Затем задайте атрибуты изображения:

1
2
3
4
5

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

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

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

1
2
3

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

LQIP

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

1
2
3
4

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

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

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

1

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

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

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

1

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

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

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

URL-адрес видеоПлатформаID
https://www.youtube.com/watch?v=H-B46URT4mgyoutubeH-B46URT4mg
https://www.twitch.tv/videos/1634779211twitch1634779211
https://www.bilibili.com/video/BV1Q44y1B7WfbilibiliBV1Q44y1B7Wf
https://www.open.spotify.com/track/3OuMIIFP5TxM8tLXMWYPGVspotify3OuMIIFP5TxM8tLXMWYPGV

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

  • compact — компактный плеер (напр. {% include embed/spotify.html id='3OuMIIFP5TxM8tLXMWYPGV' compact=1 %});
  • dark — принудительно тёмная тема (напр. {% include embed/spotify.html id='3OuMIIFP5TxM8tLXMWYPGV' dark=1 %}).

Видеофайлы

Чтобы встроить видеофайл напрямую:

1

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

URL указывает на видеофайл, например /path/to/sample/video.mp4.

Встроенное видео также принимает атрибуты:

  • poster='/path/to/poster.png' — постер, показываемый во время загрузки видео;
  • title='Text' — заголовок под видео, как у изображений;
  • 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='Demo video'
  autoplay=true
  loop=true
  muted=true
%}

Аудиофайлы

Чтобы встроить аудиофайл напрямую:

1

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

URL указывает на аудиофайл, например /path/to/audio.mp3.

Встроенное аудио также принимает атрибуты:

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

Пример со всеми атрибутами:

1
2
3
4
5
6

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

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

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

1
2
3

---
pin: true
---

Подсказки

Подсказки бывают четырёх типов: tip, info, warning и danger. Добавьте класс prompt-{type} к цитате. Например, подсказка info:

1
2

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

Синтаксис

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

1

`inline code part`

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

1

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

Блок кода

Создайте блок кода с помощью ```:

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
# содержание
```
{: file="path/to/file" }

Код Liquid

Чтобы показать фрагмент Liquid, оберните его в {% raw %} и {% endraw %}:

1
2
3
4
5
6
7

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

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

Математика

Математика отображается через MathJax. Из соображений производительности она не загружается по умолчанию; включите её так:

1
2
3

---
math: true
---

После включения добавляйте уравнения с таким синтаксисом:

  • Блочная математика добавляется через $$ math $$ с обязательными пустыми строками до и после $$.
    • Нумерация уравнений — через $$\begin{equation} math \end{equation}$$;
    • Ссылка на нумерацию — через \label{eq:label_name} в блоке уравнения и \eqref{eq:label_name} в тексте (см. пример ниже).
  • Встроенная математика (в строках) добавляется через $$ math $$ без пустых строк до и после $$.
  • Встроенная математика (в списках) добавляется через \$$ math $$.
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

<!-- 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

Mermaid — инструмент для создания диаграмм. Включите его для поста через блок YAML:

1
2
3

---
mermaid: true
---

Затем оберните код графа в ```mermaid и ```, как любой другой язык.

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

Подробнее о постах Jekyll — в Jekyll Docs: Posts.

Blogging, Tutorial
writing
This post is licensed under CC BY 4.0 by the author.