Referência de configuração: Blog List e listas de tags
Paginação, tags, textos e limites da visualização
Nesta página
Nota de versão: A validação estrita de blogPageSize exige 0.36.1 ou posterior; não está em 0.36.0. Em versões antigas, informe um inteiro positivo razoável.
Voltar ao índice de configuração. Este artigo cobre o arquivo do blog, o diretório de tags, as listas de publicações por tag e a paginação compartilhada. A referência é o código atual, não as quantidades ou cores do demo.
A entrada do blog em chinês é /zh/blog/ e a segunda página /zh/blog/2/. O diretório é /zh/tags/; use os links gerados para cada tag. Substitua zh nos demais idiomas. O modo de endereço da página inicial do idioma padrão não remove os prefixos de idioma destes caminhos.
Mescle os exemplos TypeScript ao defineThemeConfig existente em src/site.config.ts. Se theme, i18n ou pagination já existem, altere os campos internos e preserve o restante, sem duplicar objetos.
1. Quantas publicações mostrar por página
theme.blogPageSize
- Tipo:
number. - Padrão do tema:
10. - Efeito: quantidade por página no arquivo e em cada lista por tag, compartilhada. Filtra pelo idioma atual e ordena pubDate do mais recente ao mais antigo.
- Estado: ativo.
- Limites: Deve ser um inteiro positivo seguro. Zero, negativos, frações, NaN, Infinity e valores fora do intervalo seguro geram erro explícito ao resolver a configuração; não são truncados nem restaurados ao padrão. Zero não desativa paginação.
- Escopo: não altera publicações recentes na página inicial nem a quantidade por página dos Fragments. O diretório de tags não é paginado por este campo.
theme: { blogPageSize: 12 },
Mesmo vazio, o blog gera a primeira página. Com uma só página, não mostra paginação. Alterações exigem recompilar e publicar; páginas altas anteriores podem desaparecer sem redirecionamento automático.
A ordem não usa updatedDate, nome de arquivo ou cliques. Não há filtro de draft ou datas futuras, nem campo de ordenação. Veja regras de conteúdo em Escreva sua primeira publicação.
2. Entrada e páginas de tags
theme.tags.enabled
- Tipo:
boolean. - Padrão do tema:
true. - Efeito: controla entrada, diretório e listas por tag do tema, incluindo links de tags em cards e publicações.
- Estado: ativo.
- Limites: false não apaga tags do frontmatter, publicações ou arquivos já publicados. Não filtra a lista do blog por tag. A entrada rápida na lista também exige tags no idioma atual; ativado sem tags, o diretório mostra aviso vazio.
theme: { tags: { enabled: false } },
Tags vêm do array tags no frontmatter, sem cadastro em site.config. Remove espaços nas extremidades, itens vazios e duplicatas na mesma publicação. Maiúsculas importam: Astro e astro são diferentes.
O diretório ordena por número de publicações decrescente e desempata pelo texto da tag. Caracteres especiais, chinês, nomes reservados e tags longas têm codificação estável. Use os links gerados. Renomear pode mudar o caminho sem preservar a URL antiga.
Cards mostram no máximo duas tags, sem opção de quantidade. Isso não limita tags reais nem a inclusão de todas as tags válidas no diretório.
3. Janela de páginas e salto
theme.pagination.windowSize
- Tipo:
number. - Padrão do tema:
7. - Efeito: influencia números, páginas de borda e reticências; não é a quantidade de publicações.
- Estado: condicional; só há paginação com mais de uma página.
- Limites: valores normais são arredondados para baixo e limitados a 5–21. É um parâmetro da estratégia de janela, não garante que a soma de números, anterior/próxima e reticências seja igual a ele. Use inteiro finito.
theme.pagination.showJumpThreshold
- Tipo:
number. - Padrão do tema:
12. - Efeito: permite a entrada de salto somente quando o total é estritamente maior que o limite e jump.enabled é true.
- Estado: condicional.
- Limites: valores normais são arredondados para baixo, no mínimo 1. No padrão, 12 páginas não mostram salto; 13 mostram. Não é um limite de publicações e zero não força exibição incondicional.
theme.pagination.jump.enabled
- Tipo:
boolean. - Padrão do tema:
true. - Efeito: permite mostrar o formulário de salto.
- Estado e limites: condicional ao total superar o limite. false remove só o formulário, mantendo números e anterior/próxima. O salto exige JavaScript; links normais não.
theme.pagination.jump.enterToGo
- Tipo:
boolean. - Padrão do tema:
true. - Efeito: permite navegar com Enter na entrada de salto.
- Estado e limites: só vale quando o formulário existe. false impede o envio por Enter, mas mantém o botão. O cliente remove caracteres não numéricos e limita à faixa real, sem navegação para URLs arbitrárias.
Configure estes campos juntos:
theme: {
pagination: {
windowSize: 9,
showJumpThreshold: 8,
jump: { enabled: true, enterToGo: false },
},
},
A paginação também atende aos Fragments, cuja quantidade continua controlada por seu próprio pageSize. Não suponha que uma mudança feita para uma tag só afete aquela tag.
4. Estratégia visual de paginação
theme.pagination.style.enabled
- Tipo:
boolean. - Padrão do tema:
true. - Efeito: ativa variantes do contêiner e botões de página.
- Estado e limites: condicional. false usa a variante base 1, sem apagar paginação ou mudar quantidades. Não desativa todo o Cyberpunk nem controla cores aleatórias dos cards ou controles Cards/List.
theme.pagination.style.mode
- Tipo:
'random' | 'sequential' | 'fixed'. - Padrão do tema:
'random'. - Efeito: decide a escolha das variantes.
- Estado e limites: só aplica a estratégia com style.enabled true. Há três modos:
| Modo | Comportamento atual |
|---|---|
| random | A compilação define uma variante inicial estável. A inicialização do cliente sorteia novamente contêiner e botões, com possíveis repetições; não é uma animação de troca contínua |
| sequential | O contêiner segue o número da página e os botões seus próprios índices. Podem ter cores diferentes; não alterna com o tempo |
| fixed | Contêiner e botões usam a mesma variante indicada por fixedVariant |
Sem JavaScript, mantém o estilo inicial do HTML, sem sorteio no cliente.
theme.pagination.style.variants
- Tipo:
number. - Padrão do tema:
9. - Efeito: quantidade de variantes numeradas de 1 a N, não um array nem a quantidade de temas do site.
- Estado e limites: condicional. O componente arredonda valores normais para baixo e limita a 1–12. As cores neon compartilhadas atuais só definem 1–9; 10–12 não são três paletas completas extras e podem herdar cores ou usar a base. Prefira 1–9 e mantenha 9 como escolha usual. O intervalo não acrescenta cores.
theme.pagination.style.fixedVariant
- Tipo:
number. - Padrão do tema:
1. - Efeito: número da variante no modo fixed.
- Estado e limites: condicional. Arredonda valores normais para baixo e limita de 1 a variants atual. random e sequential não usam este campo para fixar estilo. Para cores neon completas, prefira 1–9 e inteiro finito.
Por exemplo, fixe a segunda aparência:
theme: {
pagination: {
style: { enabled: true, mode: 'fixed', variants: 9, fixedVariant: 2 },
},
},
Para aparência básica, mescle theme: { pagination: { style: { enabled: false } } }. Escolha o exemplo desejado; não precisa copiar os dois sequencialmente e sobrescrever.
5. Títulos, descrições e textos de paginação
Prefixo completo: i18n.locales.<locale>.messages.blog. Todos são substituições opcionais de string e condicionais ao uso do título, descrição ou controle. Os padrões usam textos integrados e fallback. A tabela traz só chinês simplificado e inglês; os outros idiomas têm seus próprios textos integrados.
| Campo | Padrão em chinês simplificado / inglês | Efeito e limites |
|---|---|---|
title |
博客 / Blog | Título da primeira página do blog e título oculto da seção; não é o título de uma publicação nem o texto fixo de troca de visualização |
pageTitle |
博客 - 第 / Blog - Page | Prefixo de título das páginas seguintes do blog e de tags; o código acrescenta o número, sem processar marcadores personalizados |
archiveDescription |
关于 AI 时代开发、Web 工程与系统架构的文章。 / Essays on AI-era craft, web engineering, and system architecture. | Metadescrição da primeira página do blog e do diretório de tags; não é o resumo de cada card |
pageDescription |
博客归档页 / Blog archive page | Prefixo da metadescrição das páginas seguintes do blog; acrescenta número e ponto. Não ocupa a mesma posição descritiva nas listas por tag |
i18n: {
locales: {
'pt-br': {
messages: {
blog: {
title: 'Arquivo de artigos',
pageTitle: 'Arquivo de artigos — página',
archiveDescription: 'Projetos, leituras e anotações de estudo.',
pageDescription: 'Página do arquivo de artigos',
},
},
},
},
},
Os campos de paginação usam o mesmo prefixo e tipo string:
| Campo | Padrão em chinês simplificado / inglês | Efeito e limites |
|---|---|---|
previous |
上一页 / Previous | Texto visível e nome acessível do link anterior; ausente na primeira página |
next |
下一页 / Next | Texto visível e nome acessível do link seguinte; ausente na última página |
paginationAria |
分页导航 / Pagination | Nome acessível do nav de paginação; não é outro título grande visível |
jumpTo |
跳转到页 / Jump to page | Texto ao lado da entrada de salto; aparece somente quando o formulário satisfaz as condições |
jumpInputLabel |
页码 / Page number | Rótulo oculto que dá nome acessível à entrada; não altera o formato |
jumpGo |
跳转 / Go | Texto do botão de salto; não altera o caminho de destino |
Também atendem às listas por tag e à paginação dos Fragments. As rotas do blog têm fallback inglês extra para jumpTo/jumpInputLabel/jumpGo vazios, mas as rotas de tags passam diretamente os valores resolvidos. Não tente ocultar controles entre páginas com strings vazias. Use jump.enabled e preserve nomes acessíveis significativos.
i18n: {
locales: {
'pt-br': {
messages: {
blog: {
previous: 'Página anterior',
next: 'Próxima página',
paginationAria: 'Paginação de artigos',
jumpTo: 'Ir para a página',
jumpInputLabel: 'Número da página',
jumpGo: 'Ir',
},
},
},
},
},
6. Textos do diretório de tags e entradas compartilhadas
Usam i18n.locales.<locale>.messages.blog, com substituições opcionais string e fallback normal. Dependem da existência da área correspondente:
| Campo | Padrão em chinês simplificado / inglês | Efeito e limites |
|---|---|---|
tags |
标签 / Tags | Entrada rápida, diretório, título de listas por tag e nomes acessíveis relacionados; não altera textos ou slugs das tags reais |
allPosts |
全部文章 / All posts | Texto para voltar a todas as publicações, também usado na página inicial; não altera a contagem |
noTags |
暂无标签 / No tags yet. | Aviso sem tags válidas no diretório; não é o aviso sem publicações no blog |
taggedPosts |
文章 / Posts | Texto da quantidade por tag e da descrição da página; não define contagem manual |
i18n: {
locales: {
'pt-br': {
messages: {
blog: {
tags: 'Explorar por tags',
allPosts: 'Voltar a todos os artigos',
noTags: 'Ainda não há tags para explorar.',
taggedPosts: 'artigos',
},
},
},
},
},
Esvaziar texto não desativa funções; pode deixar links vazios ou descrições incompletas. Desative tags com theme.tags.enabled, não com false ou string vazia no texto tags.
7. Cards/List, capas e outros limites
São comportamentos atuais, não novos campos:
- Blog e listas por tag compartilham Cards/List. Sem preferência salva, começa em cards. JavaScript permite trocar; localStorage usa a mesma chave entre blog, tags e idiomas. Sem armazenamento, ainda troca, mas pode não lembrar.
- Não há campo em site.config para visão padrão, desativar a troca, textos da visão, nomes de colunas ou cores de cards. Controles e barra de arquivo usam tabelas de idioma internas do componente e inglês para idiomas personalizados sem entrada própria. messages.blog.title não os altera.
- Cards mostram título, data, capa e até duas tags. Sem opção para resumos, quantidade de candidatos prioritários de capa ou ordem por updatedDate. Alterar a metadescrição não transforma description em resumo do card.
- As duas primeiras candidatas que realmente têm capa usam eager/high; as demais, lazy. Ocultar capas em List não garante que essas candidatas não baixem. Veja preparação e tamanho no tutorial de imagens.
- Ao trocar idioma na paginação principal, preserva a página se existir no destino; caso contrário, abre a primeira. Em listas por tag, procura o mesmo texto da tag e abre sua primeira página; sem correspondência, abre o diretório do destino. Não traduz tags nem busca sinônimos.
- Quantidade de recentes e efeito de travessia da página inicial estão no dicionário da página inicial. Navegação, busca, rodapé e comentários não são redefinidos aqui.
Não há campos específicos de lista que precisem ser documentados como compatibilidade. blogView, showExcerpt e cardTheme não são campos aceitos. Adicionar chaves arbitrárias não ativa recursos visuais sem configuração pública.
Como confirmar as alterações?
Em dev, confira primeira e demais páginas do blog, diretório e lista de uma tag. O salto exige páginas suficientes; distinga fixed de random. Veja metadescrições no head. Não avalie nomes acessíveis ou tags ocultas apenas pelos títulos grandes.
Após mudar quantidade ou nomes de tags, recompile e publique tudo, observando arquivos antigos de páginas ou tags. Antes de publicar, pare dev, execute npm run doctor e depois npm run preview. doctor já compila; não repita check e build imediatamente. Veja instalação e implantação.