﻿---
title: "Справочник настроек: Fragments"
description: "Типы, стандарты, ограничения и примеры всех настроек Fragments, сообщений и frontmatter, включая неиспользуемые поля."
url: "https://demo.anglefeint.com/ru/blog/config-fragments/"
language: "ru"
author: "Anglefeint"
published: "2026-11-13T00:00:00.000Z"
updated: "2026-11-14T00:00:00.000Z"
---

# Справочник настроек: Fragments

Для первой записи прочитайте [публикацию заметки](https://demo.anglefeint.com/ru/blog/starter-guide-5-fragments/); здесь справочные поля. Установка и файл — в [первом руководстве](https://demo.anglefeint.com/ru/blog/starter-guide-1-configure-your-site/), остальные модули — в [общем справочнике](https://demo.anglefeint.com/ru/blog/config-reference/).

Стандарты относятся к пакету, не текущему demo. Объединяйте фрагменты с существующим `defineThemeConfig({...})` в `src/site.config.ts` без повторных theme/i18n.

## Найдите нужную область

| Что изменить | Путь или место |
| --- | --- |
| Список и вход главной | `theme.fragments.enabled` |
| Число записей страницы | `theme.fragments.pageSize` |
| Отдельные комментарии заметок | `theme.fragments.comments.enabled`, подключение общее `theme.comments` |
| Заголовок, описание, подсказки, закрытие | `i18n.locales.<locale>.messages.fragments` |
| Номера страниц и быстрый переход | `theme.pagination`, тексты `messages.blog` |
| ID, время, заголовок записи | Frontmatter Markdown, не site.config |
| Число превью главной, высота, аватар | Публичных полей сейчас нет |

## theme.fragments.enabled: включение заметок

*   **Тип / стандарт:** boolean / `false`.
*   **Состояние / действие:** действует. Загружает `src/content/fragments/<locale>/**/*.md`, создаёт списки включённых языков и индекс позиционирования; главная показывает вход при контенте этого языка.
*   **Ограничения:** отключение не загружает коллекцию и не создаёт маршруты, но сохраняет файлы. Включённый пустой список показывает пустое состояние, без входа главной. Только `.md`, не `.mdx`.
*   **Пример:** `theme: { fragments: { enabled: true } }`.

Первая страница — `/<locale>/fragments/`, далее `/<locale>/fragments/2/` и т. д.; `/1/` не добавляйте. Язык должен быть включён: [языковое руководство](https://demo.anglefeint.com/ru/blog/starter-guide-languages/).

При `theme.fragments.enabled: false` dev, build и prepare-covers/doctor пропускают ссылки на изображения в тексте Fragments. Для изображений, включённых в обработку только этими ссылками, оригиналы и производные файлы больше не требуются. Ссылки на обложки и пулы `src/assets/blog/default-covers/`, `src/assets/blog/covers/originals/` по-прежнему обрабатываются и проверяются, даже если изображение используется только в Fragments. Файлы не удаляются; повторное включение возобновляет обработку Fragments.

**Примечание о версии:** Изоляция изображений при отключении доступна с 0.36.1 и отсутствует в 0.36.0. Не считайте её доступной в старых версиях.

## theme.fragments.pageSize: размер полного списка

*   **Тип / стандарт:** number / `20`.
*   **Состояние / действие:** действует на пагинацию и индекс ID→страница.
*   **Ограничения:** **безопасное целое 1–100**; дробь, 0, отрицательное и выход за диапазон вызывают ошибку, не ограничиваются автоматически. Проверяется и при отключённых заметках. Главная по-прежнему берёт три, независимо от этого поля и `theme.homeLatestCount`.
*   **Пример:** `theme: { fragments: { pageSize: 10 } }`.

В языке порядок — pubDate от нового к старому, затем ID через `localeCompare`. Не по имени файла, без исключения будущих дат. Размер страницы меняет местоположение записи; используйте стабильную ссылку ниже.

## theme.fragments.comments.enabled: комментарии заметок

*   **Тип / стандарт:** boolean / `false`.
*   **Состояние / действие:** условно. При включённых заметках карточки полного списка получают кнопку общего окна обсуждения; превью главной её не имеет.
*   **Ограничения:** независимо от `theme.comments.enabled` статей. Нужны общие данные Giscus, иначе генерация страницы заметок сообщает ошибку даже при пустом списке. Сервис/разрешения репозитория тоже должны быть настроены.
*   **Пример:** `theme: { fragments: { enabled: true, comments: { enabled: true } } }`.

Заметки без комментариев:

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

Для одних заметок статьи могут оставаться false, но нужны repo, repoId, category, categoryId. Их типы/стандарты/проверки — в [подключении Giscus](https://demo.anglefeint.com/ru/blog/config-comments/#connection), полный пример — в [комментариях только заметок](https://demo.anglefeint.com/ru/blog/config-comments/#fragment-overrides). Локальная проверка не доказывает правильность удалённых ID/прав.

Обсуждение связано с `fragment/<stable-ID>`, одинаковый ID языков общий. mapping, term, number, shareAcrossLocales статей не используются; фиксированы specific, strict `'1'`, emitMetadata `'1'`. Язык следует странице, не `theme.comments.lang`. Если статьи тоже включены, их собственная проверка остаётся.

Тема Giscus, реакции и положение ввода общие. Подробные действия — в руководстве комментариев. Script вставляется при первом щелчке; фиксированный loading eager означает сразу после щелчка, не загрузку на первом экране. Закрытие сохраняет iframe, смена записи меняет обсуждение. Примерно после 15 секунд без действительного ответа — ошибка/повтор; публичного timeout нет.

## Тексты заметок: messages.fragments

Префикс `i18n.locales.<locale>.messages.fragments`. Все **string**, меняют текст, не функцию. Стандарт — встроенный язык с откатом; ниже настоящие упрощённый китайский/английский. Отсутствие сохраняет стандарт, пустая строка переопределяет без гарантии скрытия элемента. Примеры внутри fragments.

| Поле | Стандарт упрощённого китайского / английского | Состояние, действие и ограничения | Пример |
| --- | --- | --- | --- |
| `title` | 碎片 / Fragments | Условно: заголовок списка/часть title страницы/доступное имя главной, не заголовок записи | `title: 'Короткие заметки'` |
| `description` | 沿途记录的几句话。 / Brief thoughts, kept along the way. | Условно: видимое вступление и описание списка; окно главной его не показывает | `description: 'Небольшие заметки о работе и жизни.'` |
| `empty` | 还没有碎片。 / No fragments yet. | Условно: пустой полный список; не принуждает вход главной | `empty: 'Загляните позже.'` |
| `comments` | 评论 / Comments | Условно: кнопка включённых комментариев | `comments: 'Обсудить'` |
| `close` | 关闭 / Close | Условно: текст закрытия комментариев и доступное имя закрытия главной | `close: 'Закрыть окно'` |
| `previous` | 上一页 / Previous | **Сейчас не используется**: тип принимается, реальная пагинация использует messages.blog.previous | `previous: 'Предыдущая страница'` |
| `next` | 下一页 / Next | **Сейчас не используется**: реальная пагинация использует messages.blog.next | `next: 'Следующая страница'` |
| `loading` | 正在加载评论… / Loading comments… | Условно: загрузка комментариев | `loading: 'Подключение к обсуждению…'` |
| `error` | 评论未能加载，请检查网络或评论配置后重试。 / Unable to load comments. Check your network or comment settings, then retry. | Условно: ошибка комментариев, не индекса позиционирования | `error: 'Обсуждение недоступно; попробуйте снова.'` |
| `retry` | 重试 / Retry | Условно: повтор комментариев после ошибки | `retry: 'Подключиться снова'` |
| `copyLink` | 复制碎片链接 / Copy fragment link | Условно: title/доступное имя кнопки ссылки, включаемой скриптом | `copyLink: 'Копировать ссылку на заметку'` |
| `linkCopied` | 链接已复制 / Link copied | Условно: успешное копирование | `linkCopied: 'Скопировано'` |
| `copyLinkFailed` | 未能自动复制，请复制下方链接。 / Unable to copy automatically. Copy the link below. | Условно: ошибка буфера с ручным копированием | `copyLinkFailed: 'Скопируйте ссылку вручную.'` |
| `notFound` | 找不到这条碎片，它可能已被移除。 / Fragment not found. It may have been removed. | Условно: ID не найден, не общий 404 | `notFound: 'Эта заметка больше не существует.'` |
| `indexError` | 暂时无法定位这条碎片，请刷新页面后重试。 / Unable to locate this fragment. Refresh the page and try again. | Условно: ошибка запроса/проверки индекса | `indexError: 'Не удалось найти заметку; обновите страницу и повторите.'` |

Например, только русские заголовок и описание:

```ts
i18n: {
  locales: {
    ru: {
      messages: {
        fragments: {
          title: 'Короткие заметки',
          description: 'Небольшие заметки о работе и жизни.',
        },
      },
    },
  },
},
```

## Какие общие настройки использует Fragments?

| Путь | Стандарт и действие | Ограничения, пример и описание |
| --- | --- | --- |
| `theme.pagination.*` | Восемь полей пагинации Blog List со стандартами | Только при нескольких страницах; `theme: { pagination: { windowSize: 5 } }`. [Пагинация](https://demo.anglefeint.com/ru/blog/config-blog-list/#pagination-window) и следующие разделы |
| `i18n.locales.<locale>.messages.blog.previous`, `next`, `paginationAria`, `jumpTo`, `jumpInputLabel`, `jumpGo` | string, встроенные текущего языка; видимые/доступные тексты пагинации | `previous: 'Предыдущая страница'`; [тексты](https://demo.anglefeint.com/ru/blog/config-blog-list/#pagination-messages), не одноимённые fragments |
| `i18n.locales.<locale>.messages.blog.backToTop` | string, встроенный текущего языка | Кнопка наверх полного списка; `backToTop: 'Наверх'`, [тексты статьи](https://demo.anglefeint.com/ru/blog/config-article/#article-messages) |
| `i18n.locales.<locale>.messages.home.viewAll` | string, встроенный текущего языка | Доступное имя архива окна главной вместе с названием заметок; `viewAll: 'Посмотреть всё'`, [главная](https://demo.anglefeint.com/ru/blog/config-home/#home-messages) |
| `theme.math.enabled` | boolean / `true` | Полный список определяет нужные математические стили по текущей странице; `theme: { math: { enabled: false } }`, [математика](https://demo.anglefeint.com/ru/blog/config-article/#feature-switches) |

Общие параметры `theme.comments` — в [Giscus](https://demo.anglefeint.com/ru/blog/config-comments/); здесь нужны подключение и отличия связи, а не mapping статей. `theme.toc.enabled`, OUTPUT, Red Queen и прочие функции статей списком заметок не управляют. Переключателя Cards/List Blog List у заметок нет.

## Три поля frontmatter заметки

Поля Markdown в `src/content/fragments/<locale>/`, **не site.config**. В публичной schema только три, дополнительных совместимых нет.

| Поле | Тип / стандарт | Состояние, действие и ограничения | Пример |
| --- | --- | --- | --- |
| `id` | string / нет, обязателен | Действует. Ровно 8 ASCII латинских букв/цифр, уникален внутри языка. На нём основаны ссылки/комментарии; сохраняйте после публикации | `id: 'aB3dE6gH'` |
| `pubDate` | Значение, преобразуемое в Date / нет, обязательно | Действует. Разбираемая дата для порядка и показа UTC. Рекомендуется ISO с поясом | `pubDate: '2026-11-13T08:00:00.000Z'` |
| `title` | string, необязателен / отсутствует | Условно: заголовок карточки/превью главной. Без него публикация возможна, имя файла не подставляется | `title: 'Сегодняшняя находка'` |

```md
---
id: 'aB3dE6gH'
pubDate: '2026-11-13T08:00:00.000Z'
title: 'Сегодняшняя находка'
---

Пишите текст здесь. Добавляйте изображения и код прямо в Markdown.
```

`npm run new-fragment -- --locales zh,en` создаёт набор с общими новыми ID/временем. Каждый запуск новый: перевод существующего должен сохранить ID. Между языками одинаковый ID допустим, внутри одного — ошибка. Имя файла меняется независимо, ID не должен следовать ему/номеру страницы. Старый формат автоматически не мигрирует, смена ID меняет комментарии и ссылки.

`description`, `heroImage`, `tags`, `draft` и индивидуальный `comments` не потребляются заметками: не переносите frontmatter статьи. Особенно `draft: true` не создаёт черновик. Непубличный контент не кладите во включённую коллекцию.

## Фиксированное поведение превью, изображений и ссылок

Определяется реализацией, без дополнительных публичных полей:

*   **Количество главной:** последние три текущего языка или меньше. Архив — «видимых / всего языка», другие языки не дополняют.
*   **Сводка главной:** текст, первое доступное HTTP(S)-изображение и первый код из отрендеренного содержимого. Текст до 180 Unicode code points; код до 8 строк/800 points, затем многоточие. Высота карточек ограничена с обрезкой, полный текст в списке, заголовок отдельно. Это не полный Markdown, previewCount/previewHeight нет.
*   **Изображения:** поддерживаемые локальные получают размеры/srcset из манифеста; удалённые/неподдерживаемые не обязательно оптимизируются. Первая картинка страницы полного списка eager/high, остальные lazy, decoding async. [Подготовка и файлы](https://demo.anglefeint.com/ru/blog/starter-guide-images/), heroImage заметке не нужен.
*   **Стабильные ссылки:** `/<locale>/fragments/#<ID>`, скрипт находит страницу по индексу и переходит. Новые записи/pageSize сохраняют поиск ID, удаление/смена ID — нет. Без JavaScript остаётся пагинация, не автоматический межстраничный поиск/копирование.
*   **Смена языка:** первая страница списка целевого языка, не гарантированный перевод того же ID.
*   **Публичность:** агрегат `/<locale>/fragments/index.md`. Это не переключатель поиска статей/RSS; не публикуйте чувствительные сведения.

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