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

$ опубликовано 2026-11-13 | | обновлено 2026-11-14
Контекст: Типы, стандарты, ограничения и примеры всех настроек Fragments, сообщений и frontmatter, включая неиспользуемые поля.

Список заметок, превью главной, постоянные ID и комментарии.


Вывод
слов 1.4k токенов 1.9k

Для первой записи прочитайте публикацию заметки; здесь справочные поля. Установка и файл — в первом руководстве, остальные модули — в общем справочнике.

Стандарты относятся к пакету, не текущему 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/ не добавляйте. Язык должен быть включён: языковое руководство.

При 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 } } }.

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

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

Для одних заметок статьи могут оставаться false, но нужны repo, repoId, category, categoryId. Их типы/стандарты/проверки — в подключении Giscus, полный пример — в комментариях только заметок. Локальная проверка не доказывает правильность удалённых 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: 'Не удалось найти заметку; обновите страницу и повторите.'

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

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

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

Путь Стандарт и действие Ограничения, пример и описание
theme.pagination.* Восемь полей пагинации Blog List со стандартами Только при нескольких страницах; theme: { pagination: { windowSize: 5 } }. Пагинация и следующие разделы
i18n.locales.<locale>.messages.blog.previous, next, paginationAria, jumpTo, jumpInputLabel, jumpGo string, встроенные текущего языка; видимые/доступные тексты пагинации previous: 'Предыдущая страница'; тексты, не одноимённые fragments
i18n.locales.<locale>.messages.blog.backToTop string, встроенный текущего языка Кнопка наверх полного списка; backToTop: 'Наверх', тексты статьи
i18n.locales.<locale>.messages.home.viewAll string, встроенный текущего языка Доступное имя архива окна главной вместе с названием заметок; viewAll: 'Посмотреть всё', главная
theme.math.enabled boolean / true Полный список определяет нужные математические стили по текущей странице; theme: { math: { enabled: false } }, математика

Общие параметры theme.comments — в Giscus; здесь нужны подключение и отличия связи, а не 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: 'Сегодняшняя находка'
---
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. Подготовка и файлы, heroImage заметке не нужен.
  • Стабильные ссылки: /<locale>/fragments/#<ID>, скрипт находит страницу по индексу и переходит. Новые записи/pageSize сохраняют поиск ID, удаление/смена ID — нет. Без JavaScript остаётся пагинация, не автоматический межстраничный поиск/копирование.
  • Смена языка: первая страница списка целевого языка, не гарантированный перевод того же ID.
  • Публичность: агрегат /<locale>/fragments/index.md. Это не переключатель поиска статей/RSS; не публикуйте чувствительные сведения.

Аватар, hover-анимации, рамка и высота кода сейчас не site.config-поля. Справочник не предлагает несуществующие настройки. Назад к общему справочнику.