Справочник настроек: Fragments
Список заметок, превью главной, постоянные ID и комментарии.
На этой странице
Для первой записи прочитайте публикацию заметки; здесь справочные поля. Установка и файл — в первом руководстве, остальные модули — в общем справочнике.
Стандарты относятся к пакету, не текущему 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-поля. Справочник не предлагает несуществующие настройки. Назад к общему справочнику.