Configuration Reference: Fragments

$ published 2026-11-13 | | updated 2026-11-14
Context: Actual Fragments switches, pagination, comments, interface text and content fields, including currently unused values.

Fragment lists, homepage previews, independent comments and stable links.


Output
words 1.6k tokens 2.1k

To publish first, read publish a fragment. This page is a field reference. See installation for configuration location, or the reference index for all modules.

Defaults refer to the theme package, not the demo’s configuration. Merge fragments into existing defineThemeConfig({...}) in src/site.config.ts, without duplicating theme/i18n.

Find the setting

What to change Path or location
Fragment list and homepage entry theme.fragments.enabled
Items per full-list page theme.fragments.pageSize
Independent fragment comments theme.fragments.comments.enabled, connection shared with theme.comments
Title, description, prompts and close text i18n.locales.<locale>.messages.fragments
Page numbers and jumping theme.pagination, with text from messages.blog
Per-fragment ID, time and title Markdown frontmatter, not site.config
Homepage count, height and avatar No corresponding public fields currently.

theme.fragments.enabled: enable fragments

  • Type / default: boolean / false.
  • Status / purpose: active. Loads src/content/fragments/<locale>/**/*.md, generates enabled-language lists and positioning indexes, and shows a homepage entry when that language has content.
  • Limits: off means no collection loading/list routes, without deleting files. Enabled but empty lists show an empty state and no homepage entry. Only .md, not .mdx, is loaded.
  • Example: theme: { fragments: { enabled: true } }.

The first page is /<locale>/fragments/, then /<locale>/fragments/2/, not a manually added /1/. Enable the language first; see languages.

With theme.fragments.enabled: false, dev, build and prepare-covers/doctor skip image references in Fragment content. Originals and derivatives are no longer required for images included solely through those references. Article-cover references and the src/assets/blog/default-covers/ and src/assets/blog/covers/originals/ pools still undergo preparation and validation, even if an image is used only in Fragments. Disabling deletes no files; re-enabling restores Fragment image processing.

Version note: Disabled-content image isolation requires 0.36.1 or later; 0.36.0 does not include it. Do not assume older versions provide this behavior.

theme.fragments.pageSize: full-list page size

  • Type / default: number / 20.
  • Status / purpose: active; determines list pagination and ID-to-page indexing.
  • Limits: a safe integer from 1–100. Fractions, zero, negatives and out-of-range values fail rather than clamp. It is validated even with Fragments off. Homepage previews remain the latest three, unaffected by this or theme.homeLatestCount.
  • Example: theme: { fragments: { pageSize: 10 } }.

Each language sorts by descending pubDate, then ID localeCompare on ties. Filenames do not sort content; future dates are not filtered. Page-size changes move entries between pages, so share stable links below.

theme.fragments.comments.enabled: fragment comments

  • Type / default: boolean / false.
  • Status / purpose: conditional. With Fragments enabled, each full-list card receives a comment button opening a shared dialog for that discussion. Homepage previews have no comment button.
  • Limits: independent of article theme.comments.enabled. Shared Giscus connection settings are required. Missing values fail during fragment-page generation, even for empty lists. Service/repository permissions must still work remotely.
  • Example: theme: { fragments: { enabled: true, comments: { enabled: true } } }.

Enable fragments without comments:

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

For fragment-only comments, keep articles false but configure repo, repoId, category and categoryId. See connection parameters for types/defaults/validation and fragment-only examples. Local checks cannot prove remote IDs/permissions.

Binding uses fragment/<stableID>; matching IDs share discussions across languages. Article mapping, term, number and shareAcrossLocales are ignored. Fragments force specific, strict '1', emitMetadata '1', and page-derived language instead of theme.comments.lang. Enabled article comments still undergo their own validation.

Theme, reactions and input position remain shared. The first click inserts the Giscus client; eager loading means immediately after clicking, not initial-page loading. Closing retains the iframe; switching fragments changes its discussion. About 15 seconds without a valid response shows failure/retry. No timeout setting is public.

Interface text: messages.fragments

Full prefix: i18n.locales.<locale>.messages.fragments. All fields are string values changing text, not behavior, with built-in language defaults/fallback. The table lists Simplified Chinese / English defaults. Omission retains defaults; an empty string is an override and does not guarantee removing its control. Examples belong inside the fragments object.

Field Simplified Chinese / English default Status, purpose and limits Example
title 碎片 / Fragments Conditional: list/page heading and homepage entry accessible name, not a per-fragment title. title: 'Brief notes'
description 沿途记录的几句话。 / Brief thoughts, kept along the way. Conditional: visible list introduction and page metadata; absent from the homepage expanded window. description: 'Small notes on work and everyday life.'
empty 还没有碎片。 / No fragments yet. Conditional: empty full-list notice; cannot force the homepage entry to appear. empty: 'Check back later.'
comments 评论 / Comments Conditional: button text when fragment comments are enabled. comments: 'Join the discussion'
close 关闭 / Close Conditional: comment-dialog close text and homepage close accessible name. close: 'Close window'
previous 上一页 / Previous Currently unused: accepted by types, but pagination uses messages.blog.previous. previous: 'Previous'
next 下一页 / Next Currently unused: accepted by types, but pagination uses messages.blog.next. next: 'Next'
loading 正在加载评论… / Loading comments… Conditional: comment loading status. loading: 'Connecting to discussion…'
error 评论未能加载,请检查网络或评论配置后重试。 / Unable to load comments. Check your network or comment settings, then retry. Conditional: comment failure, not positioning-index failure. error: 'Discussion unavailable; please retry.'
retry 重试 / Retry Conditional: retry button after comment-loading failure. retry: 'Reconnect'
copyLink 复制碎片链接 / Copy fragment link Conditional: share-link button title and accessible name; JavaScript enables the button. copyLink: 'Copy this fragment link'
linkCopied 链接已复制 / Link copied Conditional: successful copying. linkCopied: 'Copied'
copyLinkFailed 未能自动复制,请复制下方链接。 / Unable to copy automatically. Copy the link below. Conditional: clipboard failure, offering manual copying. copyLinkFailed: 'Copy this link manually.'
notFound 找不到这条碎片,它可能已被移除。 / Fragment not found. It may have been removed. Conditional: stable-ID lookup failure, not general 404 text. notFound: 'This fragment no longer exists.'
indexError 暂时无法定位这条碎片,请刷新页面后重试。 / Unable to locate this fragment. Refresh the page and try again. Conditional: positioning-index request or validation failure. indexError: 'Could not locate the fragment; refresh and retry.'

For example, override the English title/description only:

i18n: {
  locales: {
    en: {
      messages: {
        fragments: {
          title: 'Brief notes',
          description: 'Small notes on work and everyday life.',
        },
      },
    },
  },
},

Shared settings used by Fragments

Path Default and purpose Limits, examples and full reference
theme.pagination.* Shares the eight Blog List pagination fields/defaults. Appears only with multiple pages; for example theme: { pagination: { windowSize: 5 } }. See pagination and subsequent sections for types/ranges/examples.
i18n.locales.<locale>.messages.blog.previous、next、paginationAria、jumpTo、jumpInputLabel、jumpGo string, built-in language text for visible/accessible pagination labels. For example previous: 'Previous'; see pagination text, not matching fragments fields.
i18n.locales.<locale>.messages.blog.backToTop string, built-in language text. Full-list back-to-top button; for example backToTop: 'Back to top'. See article text.
i18n.locales.<locale>.messages.home.viewAll string, built-in language text. Homepage footer archive accessible name also combines the fragment title; for example viewAll: 'View all'. See homepage messages.
theme.math.enabled boolean / true Full lists include mathematical styles only for pages that need them. Example theme: { math: { enabled: false } }; see math switch.

See the Giscus reference for all common connection/presentation parameters. Article mapping settings are not fragment binding settings. Article contents, OUTPUT and Red Queen do not control fragment lists; Fragments also lacks the Blog List Cards/List switch.

Three per-fragment frontmatter fields

These belong to Markdown in src/content/fragments/<locale>/, not site.config. The public schema has these three fields, without additional compatibility fields.

Field Type / default Purpose, status and limits Example
id string / none, required Active. Exactly eight ASCII letters/digits, unique within a language. Links and comments depend on it; retain it after publication. id: 'aB3dE6gH'
pubDate Date-convertible value / none, required Active. Must parse as a date; determines ordering and displays in UTC. Prefer timezone-qualified ISO strings to avoid ambiguity. pubDate: '2026-11-13T08:00:00.000Z'
title optional string / unset Conditional. Optional card/homepage title. Omission is valid, with no automatic filename-based title. title: 'A small discovery today'
---
id: 'aB3dE6gH'
pubDate: '2026-11-13T08:00:00.000Z'
title: 'A small discovery today'
---

Write the content here. Add images and code directly in the Markdown body.

npm run new-fragment -- --locales zh,en generates files sharing a new ID and current timestamp. Every invocation generates a new identity. Keep an existing ID when adding translations. IDs can match across languages, but duplicates within one language fail. Filenames may change; IDs must not depend on filename/page number. Old formats are not migrated automatically, and arbitrary ID changes break discussion/link identity.

description, heroImage, tags, draft and per-fragment comments have no corresponding fragment consumers. Do not apply article frontmatter wholesale. In particular, draft: true does not create a private draft; keep unready content outside enabled collections.

No additional public fields configure the following:

  • Homepage count: latest three in the current language, or fewer when unavailable. The archive footer shows displayed/current-language total. Other languages never fill missing entries.
  • Excerpt: extracts text, first usable HTTP(S) image and first code block from rendered HTML. Text is limited to 180 Unicode code points; code to eight lines/800 code points, with ellipses on truncation. Cards crop height overflow while full content remains in the list. Titles are separate. This is not full Markdown rendering; no previewCount/previewHeight setting exists.
  • Images: supported local files receive dimensions/srcset from the manifest. Remote/unsupported images are not guaranteed optimization. Each list page’s first image uses eager/high; others lazy, all asynchronous decoding. See images for originals, variants and validation; no fragment heroImage is needed.
  • Stable links: /<locale>/fragments/#<ID>. The positioning index finds the current page and navigates if necessary, retaining ID lookup after additions/pageSize changes. Deletion or changed IDs lose the target. Without JavaScript, pagination works but cross-page lookup/copy cannot be relied upon.
  • Language switching: enters the target fragment-list first page, not necessarily the matching ID.
  • Public output: combined Markdown is /<locale>/fragments/index.md. This does not enable article search/RSS. Never publish sensitive data there.

Avatar assets, hover animation, window borders and code-preview height are not site.config fields. Return to the reference index for supported settings.