﻿---
title: "Руководство 4: опубликовать заметку"
description: "Создание Fragments, стабильные ID, изображения, превью главной, пагинация, переводы, Giscus и публикация."
url: "https://demo.anglefeint.com/ru/blog/starter-guide-5-fragments/"
language: "ru"
author: "Anglefeint"
published: "2026-11-11T00:00:00.000Z"
updated: "2026-11-14T00:00:00.000Z"
---

# Руководство 4: опубликовать заметку

Это руководство 4 из 8. [Порядок всех руководств](https://demo.anglefeint.com/ru/blog/starter-guide-1-configure-your-site/#tutorial-order) · [Справочник настроек](https://demo.anglefeint.com/ru/blog/config-reference/).

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

Статья рассчитана на текущий интеграционный starter. Если в существующем проекте нет команды или функции, сначала выполните обновление по [первому руководству](https://demo.anglefeint.com/ru/blog/starter-guide-1-configure-your-site/).

## 1\. Включите список заметок

Откройте `src/site.config.ts` и объедините `fragments` ниже с существующим `theme`. Не создавайте второй одноимённый объект:

```ts
theme: {
  fragments: {
    enabled: true,
    pageSize: 20,
    comments: { enabled: false },
  },
},
```

| Поле | Значение по умолчанию и действие |
| --- | --- |
| `theme.fragments.enabled` | `false`; после включения создаёт списки включённых языков и позволяет главной показывать превью при наличии контента |
| `theme.fragments.pageSize` | `20`; целое 1–100, число заметок на странице независимо от размера списка статей |
| `theme.fragments.comments.enabled` | `false`; включает окно комментариев заметок, дополнительно нужны настройки репозитория Giscus ниже |

Запустите `npm run dev` и откройте `/<locale>/fragments/` по адресу терминала, например `/en/fragments/` или `/zh/fragments/`. Соответствующий язык должен быть включён. Без контента показывается пустой список, создавать файл страницы не нужно. При отключённых заметках список и вход главной не создаются, но Markdown не удаляется.

## 2\. Создайте заметку стандартным способом

В корне проекта выполните:

```bash
npm run new-fragment
```

Без `--locales` или `ANGLEFEINT_LOCALES` создаются заготовки одной заметки для всех включённых языков; изначально их девять. Файлы находятся в `src/content/fragments/<locale>/`, имеют общие ID и время одного запуска, но текст не переводится. Терминал выводит реальные пути. Имя вроде `2026-11-13-q8Lm3XzP.md` содержит дату UTC и случайный ID. Откройте свой созданный файл, а не создавайте вручную имя из примера.

Только для китайского можно использовать `npm run new-fragment -- --locales zh`, для нескольких — `--locales en,zh`. Выберите нужный вариант вместо стандартного, не выполняйте всё подряд; команды не включают языки автоматически. До публикации перенесите незавершённые заготовки других языков за пределы каталога заметок.

**Каждый запуск создаёт новую заметку.** Для продолжения существующей редактируйте её файл, не запускайте создание заново. Slug не требуется, существующие файлы не перезаписываются.

В текущем starter есть скрипт `new-fragment`. Если его нет в старом проекте, убедитесь в обновлении темы и используйте CLI проекта:

```bash
npx @anglefeint/astro-theme new-fragment
```

Это альтернативная запись предыдущей команды, а не вторая команда для «той же» заметки.

## 3\. Замените текст-заполнитель, сохранив ID

В начале файла frontmatter, текст начинается после второго `---`. Сохраните созданные `id` и `pubDate`, заменив заполнитель своей мыслью. Ниже лишь формат: не заменяйте собственный ID примером:

```md
---
id: 'q8Lm3XzP'
pubDate: '2026-11-13T09:00:00+08:00'
---

Сегодня решил давнюю проблему; запишу этот небольшой успех.
```

Сейчас поддерживаются три поля frontmatter:

| Поле | Как заполнить |
| --- | --- |
| `id` | Обязателен: ровно 8 латинских букв и цифр, регистр важен. Команда создаёт и проверяет уникальность, придумывать вручную не нужно |
| `pubDate` | Обязательная разбираемая дата; рекомендуется сохранить ISO команды или указать время с часовым поясом |
| `title` | Необязательная строка заголовка карточки; без неё публикация тоже работает |

Для заголовка добавьте `title: 'Небольшой успех'` в тот же frontmatter. `description` статьи не требуется, поля обложки `heroImage` нет; изображения вставляются в текст.

Список сортируется по `pubDate` от новых к старым, при равенстве — по ID, не по имени файла. Время страницы в UTC может отличаться от введённого локального. Изменение текста или имени файла сохраняет идентичность комментариев и ссылок; изменение даты меняет порядок и страницу списка.

**После публикации сохраняйте ID.** Повтор в одном языке вызывает ошибку; не используйте ID для разных заметок. Старые UUID или длинные ID не подходят. Перед обработкой совместимости сохраните оригинал: автоматической миграции ID, ссылок и комментариев нет. Массовая смена ID — не обычная уборка файлов.

Собираются только `.md` из `src/content/fragments/`, заметки `.mdx` не поддерживаются. Нет фильтра черновиков или будущих дат: `draft: true` и будущая дата ничего не скрывают. Непубличные заметки храните вне этого каталога.

## 4\. Добавьте изображения, код и формулы

Поддерживаются обычные Markdown-абзацы, ссылки, списки и цитаты. Пример изображения:

```md
![Снимок этого результата](/images/fragments/progress.png)
```

Сначала добавьте `public/images/fragments/progress.png`. Либо положите `photo.png` рядом с заметкой и используйте `![Описание изображения](./photo.png)`. Синтаксис, размеры и сохранение в Git см. в [руководстве по изображениям](https://demo.anglefeint.com/ru/blog/starter-guide-images/).

Для кода сохраняйте ограждения Markdown и отступы:

````md
```js
const progress = {
  done: true,
};
```
````

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

При включённой общей математике заметки поддерживают встроенные `$x_1$` и отдельные формулы между строками `$$`. Рендеринг происходит при сборке, ошибка формулы останавливает компиляцию/сборку. `theme.math.enabled` отключает обработку. Синтаксис см. в [руководстве по статьям](https://demo.anglefeint.com/ru/blog/starter-guide-2-languages-and-routing/).

Dev, build и doctor, включая CI, подготавливают используемые локальные изображения: корректные производные используются повторно, отсутствующие, устаревшие или повреждённые создаются заново. Сохраняйте оригиналы; добавление `src/assets/blog/covers/`, включая manifest.json и generated/, в Git позволяет повторно использовать результаты без зависимости от кэша хостинга. Отсутствующие или недопустимые оригиналы по-прежнему вызывают ошибку. Сохраняйте Markdown вместе с оригиналами.

**Требуется 0.36.2 или новее:** Dev, build и doctor (включая CI) повторно используют корректные производные изображения и создают отсутствующие, устаревшие или повреждённые. В версии 0.36.1 перед build/CI сначала подготовьте изображения через dev или `prepare-covers`. Явная команда `prepare-covers --check` и синхронизация конфигурации остаются проверками без записи.

## 5\. Превью главной и страницы списка

При включённых заметках и контенте текущего языка под header главной появляется пиксельный аватар. Он открывает превью максимум трёх последних заметок. Отдельная настройка главной не нужна, `homeLatestCount` статей на это не влияет.

Превью может содержать текст, первое доступное изображение и первый блок кода, но не весь текст. Высота изображений и кода ограничена с обрезкой; все изображения и блоки не показываются. Вся карточка ведёт к заметке, нижнее «число превью / общее число текущего языка →» — к полному списку. Например, для двух заметок это `2 / 2`, не фиксированные три. Пустой список не показывает вход главной.

Полный список использует `theme.fragments.pageSize`. Первая страница — `/zh/fragments/`, вторая — `/zh/fragments/2/`. Вид и переходы пагинации используют `theme.pagination`, но `blogPageSize` не определяет количество заметок.

Переключение языка списка ведёт на первую страницу целевого языка, без гарантии того же перевода или номера страницы. Число переводов может различаться; итог каждого языка считается отдельно.

## 6\. Поделитесь отдельной заметкой

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

```text
https://your-domain.example/zh/fragments/#q8Lm3XzP
```

Замените домен и ID настоящими. Дата и копирование используют корень списка плюс ID независимо от текущей страницы записи. После новых заметок, изменения даты или pageSize повторная сборка и размещение обновят индекс позиционирования.

Если записи нет на странице, JavaScript по необходимости читает статический индекс языка, переходит на нужную страницу и находит её. Без JavaScript пагинация работает, но межстраничное позиционирование и копирование недоступны. При ограничениях буфера обмена показывается выделяемая ссылка для ручного копирования.

Не считайте адрес с `/2/` постоянной ссылкой. Существующая старая страница может исправить устаревший якорь, но исчезнувший номер страницы даёт обычный 404: скрипт его не перехватывает. Удалённый контент, неизвестный ID или ошибка индекса сопровождаются сообщением, не восстановлением заметки.

Все ссылки заметок используют изображение для публикации списка соответствующего языка; отдельные карточки по ID не генерируются. Стандартное изображение см. в [руководстве по изображениям](https://demo.anglefeint.com/ru/blog/starter-guide-images/).

## 7\. Добавьте перевод той же заметки

Если нужны заготовки только китайского и английского, замените стандартную команду следующей:

```bash
npm run new-fragment -- --locales zh,en
```

Файлы одного запуска имеют общий ID и время; переводите текст самостоятельно. `--locales` выбирает файлы, но не включает языки. Приоритет: `--locales` → переменная `ANGLEFEINT_LOCALES` → включённые языки проекта. Отсутствие параметра не даёт автоматического перевода.

Для английского перевода уже существующей китайской заметки скопируйте её в `src/content/fragments/en/`, сохранив `id` и `pubDate`, затем переведите заголовок и текст. Новая команда создания выдаст другой ID и не подходит для перевода «той же» записи. Переводы могут делить ID между языками, но в одном языке двух одинаковых ID быть не должно.

Переводы с одним ID используют общие комментарии. Совпадение текста или имени файла при разных ID не связывает обсуждения.

## 8\. Включите комментарии при необходимости

Если нужны только заметки, комментарии можно оставить выключенными. Для ответов читателей подготовьте публичный репозиторий, Discussions, приложение Giscus и категорию по [руководству Giscus](https://demo.anglefeint.com/ru/blog/starter-guide-4-giscus-comments/), получите настоящие ID и объедините с конфигурацией:

```ts
theme: {
  fragments: {
    enabled: true,
    comments: { enabled: true },
  },
  comments: {
    repo: 'yourname/your-repository',
    repoId: 'REPLACE_WITH_REPO_ID',
    category: 'Announcements',
    categoryId: 'REPLACE_WITH_CATEGORY_ID',
  },
},
```

Замените аккаунт, репозиторий, категорию и оба ID. Сохраните другие настройки существующего `theme.comments`. Отсутствие четырёх полей репозитория/категории вызывает ошибку; значения-заполнители не подтверждают правильность удалённой настройки. Вставлять Giscus script или устанавливать ещё один npm-пакет Giscus не нужно.

Переключатель заметок — `theme.fragments.comments.enabled`. Ради него не требуется включать комментарии статей через `theme.comments.enabled`; если они уже включены, сохраните свою настройку.

Комментарии заметок используют фиксированные `specific`, строгое совпадение и `fragment/<id>`. Они не используют mapping, term, number, shareAcrossLocales или фиксированный lang статей. Интерфейс следует языку страницы; переводы с одним ID делят обсуждение и реакции, но текст комментариев не переводится. Остальные общие настройки внешнего вида берутся из `theme.comments`.

Клиент загружается после кнопки комментариев карточки. Закрытие сохраняет экземпляр, повторное открытие или смена заметки его использует. При ошибке или неготовности примерно за 15 секунд доступен повтор: сообщение загрузки не подтверждает подключение. Для публикации посетителю нужна авторизация GitHub.

Смена ID не переносит старые комментарии, удаление заметки не удаляет обсуждение GitHub. При необходимости миграции оцените её отдельно; автоматического объединения нет.

## 9\. Проверьте перед публикацией

В dev проверьте контент, время, превью главной и страницы. Перед публикацией остановите dev и выполните:

```bash
npm run doctor
npm run preview
```

doctor включает подготовку локальных изображений, проверки и сборку. После успеха сразу повторять build не нужно. В собранном preview проверьте ссылки позиционирования и изображения, а при настроенных комментариях — окно. Preview не публикует сайт; онлайн-контент меняется после повторного размещения статических файлов.

Заметки не входят в полнотекстовый поиск статей или их RSS. При сборке создаётся `/zh/fragments/index.md` текущего языка (для других замените `zh`), объединяющий публичные заметки языка с ID, временем, текстом и стабильными ссылками, а также включаемый в AI-читаемый индекс. Это публичный экспорт, не приватная резервная копия; комментариев в нём нет.

*   Нет списка: проверьте fragments и включение целевого языка.
*   Нет аватара главной: проверьте наличие заметок именно текущего языка; контента другого языка недостаточно.
*   Создание падает на старом файле: проверьте формат ID существующих Markdown; создатель читает их для проверки уникальности.
*   Повтор ID при сборке: проверьте копии в одном языке; перевод должен лежать в другом языковом каталоге.
*   Ошибка изображений: подготовьте и сохраните оригиналы, манифест и производные по [руководству изображений](https://demo.anglefeint.com/ru/blog/starter-guide-images/).
*   Ошибка комментариев: проверьте настоящие ID, разрешения приложения, категорию, сеть и блокировки браузера; не меняйте ID заметки снова и снова.

Для обновления см. [первое руководство](https://demo.anglefeint.com/ru/blog/starter-guide-1-configure-your-site/).

## Навигация по руководствам и настройкам

[Назад: изображения](https://demo.anglefeint.com/ru/blog/starter-guide-images/) · [Далее: настройка страниц и функций](https://demo.anglefeint.com/ru/blog/starter-guide-3-comments-about-and-theme-toggles/) · [Все восемь руководств](https://demo.anglefeint.com/ru/blog/starter-guide-1-configure-your-site/#tutorial-order).

Связанные настройки: [заметки, пагинация и поля](https://demo.anglefeint.com/ru/blog/config-fragments/), [комментарии заметок](https://demo.anglefeint.com/ru/blog/config-comments/). Полные пути, значения по умолчанию и ограничения — в [общем справочнике](https://demo.anglefeint.com/ru/blog/config-reference/).
