Referência de configuração: Fragments

$ publicado 2026-11-13 | | atualizado 2026-11-14
Contexto: Tipos, padrões e limites das configurações de Fragments, textos, paginação e IDs estáveis.

Lista, prévia inicial, comentários e campos do conteúdo


Saída
palavras 2.0k tokens 2.6k

Para publicar primeiro, leia Publique um fragment. Este artigo é uma referência. Veja instalação e localização da configuração no primeiro tutorial e outros módulos no índice de configuração.

Os padrões são os do pacote do tema, não os valores atuais do demo. Mescle todos os trechos ao defineThemeConfig({...}) existente em src/site.config.ts, sem duplicar theme ou i18n.

Encontre o que deseja alterar

O que alterar Caminho ou local
Ativar a lista de fragments e a entrada na página inicial theme.fragments.enabled
Quantidade por página na lista completa theme.fragments.pageSize
Comentários independentes dos fragments theme.fragments.comments.enabled; conexão compartilhada com theme.comments
Título, descrição, avisos e texto de fechar i18n.locales.<locale>.messages.fragments
Paginação e salto de página theme.pagination, com textos de messages.blog
ID, data e título do conteúdo Frontmatter Markdown; não é site.config
Quantidade na página inicial, altura e avatar Sem campos públicos correspondentes atualmente

theme.fragments.enabled: ativar fragments

  • Tipo / padrão: boolean / false.
  • Estado / efeito: ativo. Carrega src/content/fragments/<locale>/**/*.md e gera listas e índice de localização dos idiomas ativos. A entrada inicial aparece quando há conteúdo no idioma atual.
  • Limites: desativar impede o carregamento da coleção e a geração das rotas, mas preserva os arquivos. Ativado sem conteúdo, mostra estado vazio na lista e nenhuma entrada inicial. Só lê .md, não .mdx.
  • Exemplo: theme: { fragments: { enabled: true } }.

A primeira página é /<locale>/fragments/; a segunda começa em /<locale>/fragments/2/. Não acrescente /1/ à primeira. O idioma precisa estar ativo; veja o tutorial de idiomas.

Com theme.fragments.enabled: false, dev, build e prepare-covers/doctor ignoram referências de imagens no corpo dos Fragments. Imagens incluídas somente por essas referências deixam de exigir originais ou derivados. Referências de capas e os conjuntos src/assets/blog/default-covers/ e src/assets/blog/covers/originals/ continuam preparados e validados, mesmo para imagens usadas só em Fragments. Nenhum arquivo é apagado; reativar restaura o processamento de Fragments.

Nota de versão: O isolamento de imagens ao desativar exige 0.36.1 ou posterior; não está em 0.36.0. Não presuma esse comportamento em versões antigas.

theme.fragments.pageSize: quantidade por página da lista completa

  • Tipo / padrão: number / 20.
  • Estado / efeito: ativo; controla a paginação completa e o índice de ID para página.
  • Limites: deve ser inteiro seguro de 1 a 100. Frações, zero, negativos ou valores fora do intervalo geram erro, sem truncamento automático. pageSize é validado mesmo com fragments desativados. A prévia inicial continua com as três entradas mais recentes, independente deste campo e de theme.homeLatestCount.
  • Exemplo: theme: { fragments: { pageSize: 10 } }.

No mesmo idioma, ordena pubDate do mais novo ao mais antigo e desempata por localeCompare do ID. Não ordena por nome de arquivo nem exclui datas futuras. Mudar a quantidade pode mudar a página de um conteúdo; compartilhe o link estável abaixo.

theme.fragments.comments.enabled: comentários dos fragments

  • Tipo / padrão: boolean / false.
  • Estado / efeito: condicional. Com fragments ativos, mostra um botão em cada card da lista completa; abre a janela compartilhada e carrega a discussão da entrada. A prévia inicial não mostra comentários.
  • Limites: independente de theme.comments.enabled, o controle dos comentários de publicações. Exige também a conexão Giscus compartilhada; dados ausentes causam erro ao gerar páginas de fragments, mesmo com lista vazia. Serviço e permissões do repositório precisam estar corretos.
  • Exemplo: theme: { fragments: { enabled: true, comments: { enabled: true } } }.

Ativar apenas fragments, sem comentários:

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

Para comentários só nos fragments, o controle das publicações pode continuar false, mas repo, repoId, category e categoryId ainda são obrigatórios. Veja tipos, padrões e validação em conexão Giscus e um exemplo completo em comentários apenas nos fragments. A validação local não comprova permissões nem IDs remotos.

A discussão usa fragment/<ID-estavel>. Conteúdos de idiomas diferentes com o mesmo ID compartilham a discussão. Não usa mapping, term, number nem shareAcrossLocales das publicações. Fragments fixam mapping specific, strict '1' e emitMetadata '1'; o idioma acompanha a página, sem usar theme.comments.lang. Se comentários de publicações também estiverem ativos, sua própria validação continua sendo executada.

Tema, reações e posição do campo compartilham as opções Giscus; veja a operação completa no tutorial de comentários. O script só é inserido no primeiro clique. loading é fixo em eager: carrega imediatamente após clicar, sem antecipar na primeira tela. Fechar mantém o iframe criado; mudar de entrada troca a discussão. Sem resposta válida após cerca de 15 segundos, mostra falha e nova tentativa; não há timeout público configurável.

Textos da interface: messages.fragments

Prefixo completo: i18n.locales.<locale>.messages.fragments. Cada campo abaixo é string e só altera textos. Os padrões são os textos integrados do idioma atual, com fallback. A tabela mostra apenas padrões em chinês simplificado / inglês. Omitir mantém o padrão; string vazia é uma substituição explícita e não garante ocultar controles. Os exemplos pertencem ao objeto fragments.

Campo Padrão em chinês simplificado / inglês Estado, efeito e limites Exemplo
title 碎片 / Fragments Condicional: título da lista, parte do título da página e nome acessível da entrada inicial; não é o título individual title: 'Anotações rápidas'
description 沿途记录的几句话。 / Brief thoughts, kept along the way. Condicional: apresentação visível e descrição da lista; não aparece na janela inicial description: 'Pequenas notas sobre trabalho e vida cotidiana.'
empty 还没有碎片。 / No fragments yet. Condicional: lista completa sem conteúdo; não força a entrada na página inicial empty: 'Volte mais tarde.'
comments 评论 / Comments Condicional: botão quando comentários de fragments estão ativos comments: 'Participar da discussão'
close 关闭 / Close Condicional: fechar comentários e nome acessível do botão da janela inicial close: 'Fechar janela'
previous 上一页 / Previous Não usado atualmente: aceito pelo tipo, mas a paginação usa messages.blog.previous previous: 'Página anterior'
next 下一页 / Next Não usado atualmente: aceito pelo tipo, mas a paginação usa messages.blog.next next: 'Próxima página'
loading 正在加载评论… / Loading comments… Condicional: estado de carregamento dos comentários loading: 'Conectando à discussão…'
error 评论未能加载,请检查网络或评论配置后重试。 / Unable to load comments. Check your network or comment settings, then retry. Condicional: falha ao carregar comentários; não representa erro do índice de localização error: 'A discussão está indisponível; tente novamente.'
retry 重试 / Retry Condicional: botão para tentar novamente após falha nos comentários retry: 'Reconectar'
copyLink 复制碎片链接 / Copy fragment link Condicional: título e nome acessível do botão de compartilhar, ativado por script copyLink: 'Copiar link desta nota'
linkCopied 链接已复制 / Link copied Condicional: confirmação de cópia linkCopied: 'Copiado'
copyLinkFailed 未能自动复制,请复制下方链接。 / Unable to copy automatically. Copy the link below. Condicional: cópia automática falhou; pede cópia manual copyLinkFailed: 'Copie este link manualmente.'
notFound 找不到这条碎片,它可能已被移除。 / Fragment not found. It may have been removed. Condicional: falha ao localizar ID estável; não é um texto geral de 404 notFound: 'Esta nota não existe mais.'
indexError 暂时无法定位这条碎片,请刷新页面后重试。 / Unable to locate this fragment. Refresh the page and try again. Condicional: falha ao solicitar ou validar o índice de localização indexError: 'Não foi possível localizar; atualize e tente novamente.'

Por exemplo, substitua só título e descrição em português brasileiro:

i18n: {
  locales: {
    'pt-br': {
      messages: {
        fragments: {
          title: 'Anotações rápidas',
          description: 'Pequenas notas sobre trabalho e vida cotidiana.',
        },
      },
    },
  },
},

Quais configurações gerais Fragments também usa?

Caminho Padrão e efeito Limites, exemplo e detalhes
theme.pagination.* Compartilha os oito campos e padrões de paginação do Blog List Paginação só aparece com mais de uma página; exemplo theme: { pagination: { windowSize: 5 } }. Tipos, limites e exemplos em paginação e nas seções seguintes
i18n.locales.<locale>.messages.blog.previous、next、paginationAria、jumpTo、jumpInputLabel、jumpGo string, textos integrados do idioma atual para a paginação visível e acessível Exemplo previous: 'Página anterior'; veja os textos de paginação, sem alterar campos homônimos de fragments
i18n.locales.<locale>.messages.blog.backToTop string, texto integrado do idioma atual Botão de voltar ao topo na lista completa; exemplo backToTop: 'Voltar ao topo', veja os textos da publicação
i18n.locales.<locale>.messages.home.viewAll string, texto integrado do idioma atual O nome acessível do arquivo na janela inicial combina também o título dos fragments; exemplo viewAll: 'Ver tudo', veja textos da página inicial
theme.math.enabled boolean / true A lista completa avalia se o conteúdo da página precisa de estilos matemáticos; exemplo theme: { math: { enabled: false } }, veja ativar matemática

Veja todos os parâmetros compartilhados de theme.comments no dicionário Giscus. Este artigo distingue conexão e vínculo dos fragments, sem tratar mapeamentos de publicações como configurações de fragments. theme.toc.enabled, OUTPUT e Red Queen das publicações não controlam a lista de fragments, que também não tem a troca Cards/List do Blog List.

Os três campos de frontmatter de um fragment

São campos dos arquivos Markdown em src/content/fragments/<locale>/; não os escreva em site.config. O schema público atual tem só estes três campos, sem campos adicionais de compatibilidade.

Campo Tipo / padrão Efeito, estado e limites Exemplo
id string / nenhum, obrigatório Ativo. Exatamente 8 letras ASCII ou dígitos, sem repetição no mesmo idioma. Links e comentários dependem dele; não altere após publicar id: 'aB3dE6gH'
pubDate Valor de data convertível em Date / nenhum, obrigatório Ativo. Precisa ser uma data válida; define ordenação e aparece em UTC. Prefira string ISO com fuso para evitar ambiguidade pubDate: '2026-11-13T08:00:00.000Z'
title string, opcional / não definido Condicional. Título opcional do card, também usado na prévia inicial. Pode publicar sem ele; o nome do arquivo não vira título automaticamente title: 'Uma descoberta de hoje'
---
id: 'aB3dE6gH'
pubDate: '2026-11-13T08:00:00.000Z'
title: 'Uma descoberta de hoje'
---

Escreva o conteúdo aqui. Insira imagens e código diretamente no corpo Markdown.

npm run new-fragment -- --locales zh,en gera arquivos com um novo ID compartilhado e a data atual. Cada execução gera outro ID. Para traduzir uma entrada existente, preserve o ID original. Idiomas diferentes podem usar o mesmo ID; duplicatas no mesmo idioma geram erro. O nome do arquivo pode mudar, mas o ID não acompanha nome ou página. IDs antigos não são migrados automaticamente; alterá-los muda o vínculo dos comentários e a URL compartilhada.

description, heroImage, tags, draft e comments individual não têm lógica correspondente para fragments. Não copie o frontmatter das publicações. Em especial, draft: true não torna o fragment um rascunho; não coloque conteúdo privado numa coleção ativa.

São definidos pela implementação, sem campos públicos adicionais:

  • Quantidade inicial: as três entradas mais recentes do idioma atual, ou a quantidade real se houver menos. O link do arquivo mostra “quantidade exibida / total do idioma”. Não busca outros idiomas para completar.
  • Resumo inicial: extrai texto, primeira imagem HTTP(S) utilizável e primeiro bloco de código do conteúdo renderizado. Texto até 180 pontos de código Unicode; código até 8 linhas e 800 pontos, acrescentando reticências ao exceder. Os cards limitam a altura e ocultam o excesso; o conteúdo completo continua na lista. O título aparece separado. Não é renderização Markdown completa nem há previewCount ou previewHeight configuráveis.
  • Imagens: imagens locais compatíveis recebem dimensões e srcset pelo manifesto existente. Imagens remotas ou não compatíveis não têm otimização garantida. Na lista completa, a primeira imagem de cada página é eager / high e as demais lazy, todas com decodificação assíncrona. Veja originais, tamanhos e validação no tutorial de imagens; não precisa adicionar heroImage aos fragments.
  • Links estáveis: /<locale>/fragments/#<ID>. O script encontra a página pelo índice e redireciona se necessário. Novas entradas ou alterações de pageSize preservam a localização por ID; remover conteúdo ou mudar o ID perde o destino antigo. Sem JavaScript, a paginação normal funciona, mas não dependa da localização automática entre páginas ou do botão de copiar.
  • Troca de idioma: leva à primeira página de fragments do idioma escolhido, sem garantir localizar diretamente a tradução do mesmo ID.
  • Conteúdo público: a saída Markdown agregada é /<locale>/fragments/index.md. Não controla a busca interna nem RSS de publicações. Não inclua informações sensíveis em conteúdo público.

Avatar, animação de hover, bordas da janela e altura da prévia de código não são opções de site.config atualmente. O dicionário não oferece configurações inexistentes. Volte ao índice de configuração para outros módulos.