Como criar um blog com Astro do zero: guia completo da página inicial à implantação em 1 hora

Um blog técnico carrega por completo em 0,8 segundo, e a navegação entre páginas é muito fluida. Aí você olha para o próprio blog em WordPress: são 3 segundos diante de uma tela em branco, tempo suficiente para dar vontade de fechar a página. Eu já tinha experimentado Hexo, Hugo e até Gatsby, mas sempre travava em alguma etapa: a documentação oficial parecia confusa, os tutoriais eram fragmentados e, do início à implantação, sempre parecia faltar alguma coisa. O desempenho do Astro é excelente, a experiência de desenvolvimento também, e o processo inteiro é muito mais simples do que eu imaginava.

Neste artigo, você vai acompanhar todo o processo, do zero à implantação, para colocar no ar em até 1 hora um blog completo com página inicial, lista de artigos, tags e categorias e feed RSS. São etapas práticas, sem enrolação.

Capítulo 1: por que escolher o Astro? (Não é publicidade, ele é realmente bom)

A diferença de desempenho é tão grande assim?

Para ser sincero, no começo eu também fiquei desconfiado. O site oficial dizia que o Astro era “40% mais rápido que frameworks React tradicionais” e que tinha “zero JavaScript por padrão”. Parece conversa de marketing, não é? Mas, depois que migrei de verdade meu blog em WordPress para o Astro, os números falaram por si:

• Tempo de carregamento inicial: caiu de 3,2 para 0,8 segundo
• Nota do Lighthouse: chegou diretamente a 100 (antes era apenas 65 no WordPress)
• Volume de JavaScript: caiu de 280 KB para menos de 20 KB

Talvez você esteja se perguntando como é possível conseguir uma melhora tão grande. O segredo está na ideia central do Astro: prioridade para o conteúdo e JavaScript carregado sob demanda. Por padrão, ele gera HTML e CSS puros e só carrega JavaScript nos lugares em que você realmente precisa de interatividade. É o oposto da abordagem de frameworks como o React, que costumam levar todo o conjunto para a página.

Fiz uma comparação interessante: usei o mesmo artigo em Next.js e Astro. No primeiro carregamento, o Next.js trazia o runtime do framework, com cerca de 100 KB, enquanto o Astro entregava um arquivo HTML limpo. Para um blog, em que a leitura é o principal, a diferença é enorme.

Como é a experiência de desenvolvimento?

Depois do desempenho, vale falar da experiência de desenvolvimento. O que mais gosto no Astro é a arquitetura Islands. O nome parece sofisticado, mas a ideia é simples: JavaScript apenas onde existe interação.

Imagine uma página de artigo:

• Conteúdo principal → HTML estático (rápido)
• Área de comentários → componente React (interativo)
• Barra de navegação → componente Vue (sim, dá para combinar!)

Essa flexibilidade evita transformar o site inteiro em uma SPA por causa de um pequeno recurso. Outro ponto muito amigável para iniciantes é que você escreve os artigos diretamente em Markdown, sem precisar lidar com banco de dados ou painel administrativo. Hoje escrevo Markdown no VS Code, envio ao GitHub e o site é implantado automaticamente. Muito confortável.

E em comparação com outros frameworks?

Sei que você quer fazer essa pergunta, porque eu também passei um bom tempo em dúvida. Vamos ser objetivos e comparar em uma tabela:

Minha recomendação:

• Para criar um blog ou site de documentação técnica, escolha primeiro o Astro: desempenho e experiência de desenvolvimento são ótimos
• Para e-commerce ou aplicações com interações complexas, o Next.js continua mais adequado
• Para o blog estático mais simples possível, sem personalizações, o Hexo já resolve
• Se uma equipe sem perfil técnico precisa publicar artigos em um painel, o WordPress ainda é a melhor escolha

Além disso, dados de 2025 indicam que os downloads do Astro no npm já passaram de 3 milhões e sua participação de mercado cresceu para 18%. Cada vez mais desenvolvedores estão escolhendo a ferramenta; ela deixou de ser um framework de nicho.

Capítulo 2: preparação do ambiente (5 minutos)

Instale o Node.js, caso ainda não tenha

O Astro exige Node.js v18 ou superior. Primeiro, verifique suas versões:

node -v
npm -v

Se os números de versão aparecerem, pule esta etapa. Caso contrário, acesse o site oficial do Node.js e baixe a versão LTS.

Uma armadilha para usuários do Windows: durante a instalação, marque “Add to PATH”; caso contrário, os comandos não serão encontrados mais adiante. Alguns antivírus também podem bloquear a instalação via npm. Depois de instalar, vale reiniciar o terminal.

Crie o projeto Astro

Esta etapa é mais simples do que parece. Abra o terminal e digite:

npm create astro@latest

Várias opções vão aparecer. Não se preocupe; escolha assim:

1. Nome do projeto: use qualquer nome, como my-blog
2. Template: escolha Blog com as setas e pressione Enter
3. Instalar dependências: selecione Yes
4. Configuração do TypeScript: escolha Strict ou Strictest (acredite, a verificação de tipos evita muitos bugs)
5. Inicializar um repositório Git: selecione Yes

O processo leva cerca de 1 ou 2 minutos e baixa automaticamente o template e as dependências.

Por que recomendo o template Blog? Porque ele já traz o código básico para a lista de artigos, tags e categorias e feed RSS. Isso poupa muito tempo em comparação com um template vazio. Na primeira vez, comecei do zero e gastei duas horas apenas com paginação.

Inicie o servidor de desenvolvimento

Entre no diretório do projeto e inicie o servidor:

cd my-blog
npm run dev

Quando aparecer Local: http://localhost:4321, tudo deu certo. Abra esse endereço no navegador e você verá uma estrutura de blog pronta para usar.

Alertas para iniciantes:

• Se a porta 4321 estiver ocupada, altere server.port em astro.config.mjs
• Se aparecer o erro EACCES, pode ser um problema de permissão; tente sudo npm run dev no Mac/Linux
• Se os caracteres aparecerem corrompidos, confirme que a codificação do terminal é UTF-8

Pronto: o ambiente está preparado. Você já tem um blog Astro em execução. Agora vamos entender a função de cada arquivo.

Capítulo 3: estrutura do projeto em detalhes (entenda cada diretório)

Como é a árvore do projeto?

Abra a pasta my-blog no VS Code ou em outro editor. Você verá esta estrutura:

my-blog/
├── src/
│   ├── pages/           # Páginas de rota; o nome do arquivo define a URL
│   ├── layouts/         # Templates de layout (cabeçalho, rodapé etc.)
│   ├── components/      # Componentes reutilizáveis (botões, cartões etc.)
│   └── content/         # Seus artigos em Markdown ficam aqui
├── public/              # Recursos estáticos (imagens, fontes, favicon)
├── astro.config.mjs     # Arquivo de configuração do Astro
└── package.json         # Dependências do projeto

Parece um projeto frontend comum, certo? Mas o Astro tem alguns detalhes especiais. Ao entendê-los, fica claro por que ele é tão fácil de usar.

Diretório pages/: cada arquivo é uma rota

Este é um dos recursos de que mais gosto no Astro. Não é preciso configurar rotas: cada nome de arquivo corresponde automaticamente a uma URL.

• pages/index.astro → página inicial /
• pages/about.astro → página Sobre /about
• pages/blog/index.astro → lista do blog /blog
• pages/blog/[...slug].astro → página de artigo /blog/xxx

O último arquivo, [...slug].astro, é uma rota dinâmica. O trecho entre colchetes vira uma variável, e o arquivo processa todos os links de artigos abaixo de /blog/.

Vultr - Servidor cloud NVMe de alto desempenho, 32 locais globais, deploy Docker com um clique

Ver preços →Anúncio

É muito mais simples que o sistema de rotas do Next.js. Quando migrei do Next, gostei desse desenho imediatamente.

Diretório content/: onde ficam os artigos

Abra src/content/blog/. A pasta já contém alguns artigos de exemplo. Cada artigo é um arquivo .md ou .mdx com um frontmatter no início, ou seja, a parte cercada por três hífens:

---

title: 'Meu primeiro artigo'
description: 'Este é um artigo de teste'
pubDate: 'Dec 02 2025'
heroImage: '/blog-placeholder.jpg'
tags: ['Astro', 'Tutorial']

---

O texto começa aqui...

O Astro reconhece esses dados automaticamente, e você pode acessá-los na página com algo como post.data.title. Ele também verifica os tipos: se você escrever um nome de campo errado, a compilação mostrará um erro. É ótimo para quem gosta de consistência.

layouts/ e components/: reutilize seu código

O diretório layouts/ guarda layouts de página, como cabeçalho, rodapé e barra lateral compartilhados por todos os artigos. O template Blog já inclui os layouts BaseLayout.astro e BlogPost.astro.

Em components/ ficam elementos reutilizáveis, como botões, cartões e nuvens de tags. Eles podem ser escritos com a sintaxe do Astro ou diretamente em React/Vue, oferecendo bastante flexibilidade.

Diretório public/: cópia direta para a saída

Os arquivos daqui são copiados sem alterações para a raiz do site final. Por exemplo, depois da implantação, public/favicon.ico estará em https://seu-dominio/favicon.ico.

Normalmente coloco aqui as imagens dos artigos, os arquivos de fonte e o robots.txt.

astro.config.mjs: o arquivo principal de configuração

Este arquivo controla o comportamento do Astro. As configurações mais usadas são:

export default defineConfig({
  site: 'https://seu-dominio.com',  // Domínio da implantação
  integrations: [mdx()],          // Plugins (extensões de Markdown, RSS etc.)
  server: {
    port: 4321                    // Porta do servidor de desenvolvimento
  }
})

Você não precisa alterar muita coisa agora. Volte a este arquivo quando adicionar recursos mais adiante.

Entender essa estrutura é realmente importante. Já vi muita gente começar a programar sem saber onde colocar os arquivos e acabar com um projeto completamente desorganizado. Cinco minutos aqui podem economizar uma hora depois.

Capítulo 4: implementação dos principais recursos (agora começa a parte importante)

4.1 Layout da página inicial: mostre os artigos mais recentes

O template Blog já fornece a estrutura da página inicial, mas vamos ajustá-la um pouco para deixá-la mais útil. Abra src/pages/index.astro; você verá um código parecido com este:

---

import { getCollection } from 'astro:content';
import BaseLayout from '../layouts/BaseLayout.astro';

// Busca todos os artigos do blog, ordena por data e seleciona os cinco mais recentes
const allPosts = (await getCollection('blog'))
  .sort((a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf())
  .slice(0, 5);

---

<BaseLayout>
  <h1>Bem-vindo ao meu blog</h1>
  <ul>
    {allPosts.map((post) => (
      <li>
        <a href={`/blog/${post.slug}/`}>{post.data.title}</a>
        <time>{post.data.pubDate.toDateString()}</time>
      </li>
    ))}
  </ul>
</BaseLayout>

O que este código faz?

1. Usa getCollection('blog') para buscar todos os artigos
2. Ordena-os pela data de publicação em ordem decrescente, com os mais recentes primeiro
3. Usa slice(0, 5) para selecionar apenas os cinco primeiros
4. Percorre os artigos e renderiza uma lista

Armadilha para iniciantes: use .valueOf() ao ordenar datas. Caso contrário, a comparação será feita como texto e a ordem ficará incorreta.

4.2 Página com a lista de artigos e paginação

Crie src/pages/blog/index.astro, caso o template ainda não tenha esse arquivo, e implemente uma lista completa:

---

import { getCollection } from 'astro:content';
import BaseLayout from '../../layouts/BaseLayout.astro';

const allPosts = (await getCollection('blog'))
  .sort((a, b) => b.data.pubDate.valueOf() - a.data.pubDate.valueOf());

const pageSize = 10;
const currentPage = 1;
const totalPages = Math.ceil(allPosts.length / pageSize);
const posts = allPosts.slice(0, pageSize);

---

<BaseLayout title="Lista de artigos">
  <h1>Todos os artigos</h1>

  <div class="post-list">
    {posts.map((post) => (
      <article>
        <h2><a href={`/blog/${post.slug}/`}>{post.data.title}</a></h2>
        <p>{post.data.description}</p>
        <time>{post.data.pubDate.toLocaleDateString('pt-BR')}</time>
        <div class="tags">
          {post.data.tags?.map(tag => <span>#{tag}</span>)}
        </div>
      </article>
    ))}
  </div>

  {totalPages > 1 && (
    <div class="pagination">
      <span>Página {currentPage} de {totalPages}</span>
    </div>
  )}
</BaseLayout>

Aqui simplifiquei a lógica da paginação. Em um projeto real, você pode usar a função paginate() do Astro para gerar as páginas automaticamente. Mas, para blogs com poucos artigos, menos de 100, uma única página também pode ser suficiente.

Sugestões para melhorar a experiência:

• Adicione uma estimativa de tempo de leitura, calculada pela quantidade de caracteres dividida por 400 caracteres por minuto
• Limite o resumo a 150 caracteres e acrescente reticências
• Adicione miniaturas com o campo heroImage

4.3 Página de artigo: o núcleo do blog

Esta é a parte mais importante e usa uma rota dinâmica. Se o template Blog já tiver src/pages/blog/[...slug].astro, edite-o; caso contrário, crie o arquivo:

---

import { getCollection } from 'astro:content';
import BlogPost from '../../layouts/BlogPost.astro';

// Gera o caminho estático de cada artigo
export async function getStaticPaths() {
  const posts = await getCollection('blog');
  return posts.map(post => ({
    params: { slug: post.slug },
    props: { post },
  }));
}

const { post } = Astro.props;
const { Content } = await post.render();

---

<BlogPost {...post.data}>
  <Content />
</BlogPost>

A mágica deste código:

• getStaticPaths() é executada durante a compilação e gera um HTML estático para cada artigo
• post.render() transforma o Markdown em um componente HTML
• <Content /> representa o conteúdo do artigo

Pontos que costumam confundir iniciantes:

1. O destaque de código não funciona: instale o plugin Shiki, que já vem no template Blog
2. O Markdown não tem uma boa aparência: recomendo instalar @tailwindcss/typography
3. O caminho das imagens está errado: coloque as imagens em public/ e use /images/xxx.jpg

Para adicionar um sumário de navegação, use o plugin comunitário remark-toc e configure-o em astro.config.mjs:

import { defineConfig } from 'astro/config';
import remarkToc from 'remark-toc';

export default defineConfig({
  markdown: {
    remarkPlugins: [remarkToc],
  },
});

4.4 Sistema de tags e categorias: organize melhor o conteúdo

Crie src/pages/tags/[tag].astro para implementar o filtro por tag:

---

import { getCollection } from 'astro:content';
import BaseLayout from '../../layouts/BaseLayout.astro';

export async function getStaticPaths() {
  const allPosts = await getCollection('blog');

  // Reúne todas as tags únicas
  const allTags = [...new Set(allPosts.flatMap(post => post.data.tags || []))];

  // Gera uma página para cada tag
  return allTags.map(tag => ({
    params: { tag },
    props: {
      posts: allPosts.filter(post =>
        post.data.tags?.includes(tag)
      ).sort((a, b) =>
        b.data.pubDate.valueOf() - a.data.pubDate.valueOf()
      ),
    },
  }));
}

const { tag } = Astro.params;
const { posts } = Astro.props;

---

<BaseLayout title={`Tag: ${tag}`}>
  <h1>Artigos com #{tag} ({posts.length})</h1>

  <ul>
    {posts.map((post) => (
      <li>
        <a href={`/blog/${post.slug}/`}>{post.data.title}</a>
      </li>
    ))}
  </ul>
</BaseLayout>

Assim, cada tag gera uma página própria, como /tags/astro ou /tags/tutorial.

Opção avançada: crie uma página de nuvem de tags em src/pages/tags/index.astro, mostre todas as tags e a quantidade de artigos e varie o tamanho da fonte de acordo com essa quantidade. O resultado fica bem interessante.

4.5 Feed RSS: avise os leitores sobre atualizações

Instale o plugin de RSS:

npx astro add rss

Crie src/pages/rss.xml.js:

import rss from '@astrojs/rss';
import { getCollection } from 'astro:content';

export async function GET(context) {
  const posts = await getCollection('blog');

  return rss({
    title: 'Meu blog de tecnologia',
    description: 'Experiências e aprendizados sobre desenvolvimento frontend',
    site: context.site,
    items: posts.map((post) => ({
      title: post.data.title,
      pubDate: post.data.pubDate,
      description: post.data.description,
      link: `/blog/${post.slug}/`,
    })),
  });
}

Depois da implantação, o endereço do feed será https://seu-dominio.com/rss.xml. Embora menos pessoas usem RSS hoje, incluí-lo ainda dá um toque profissional a um blog técnico.

Neste ponto, os principais recursos estão prontos. Você tem um sistema completo com página inicial, lista de artigos, páginas individuais, tags e categorias e feed RSS. Agora vamos deixá-lo mais amigável para os mecanismos de busca.

Capítulo 5: otimização de SEO (ajude as pessoas a encontrar seu blog)

Criar o blog não é o fim: as pessoas também precisam encontrá-lo. Esse é o objetivo do SEO, ou otimização para mecanismos de busca. A boa notícia é que o Astro já parte com vantagens: HTML estático, carregamento rápido e tags semânticas, características valorizadas pelos buscadores.

Configure metatags: explique o conteúdo aos mecanismos de busca

Abra src/layouts/BaseLayout.astro, ou seu arquivo de layout base, e adicione estas tags dentro de <head>:

---

interface Props {
  title: string;
  description?: string;
  image?: string;
}

const { title, description = 'Meu blog de tecnologia', image = '/og-image.jpg' } = Astro.props;
const canonicalURL = new URL(Astro.url.pathname, Astro.site);

---

<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width" />
  <link rel="icon" type="image/svg+xml" href="/favicon.svg" />

  <title>{title} | Meu blog</title>
  <meta name="description" content={description} />
  <link rel="canonical" href={canonicalURL} />

  <!-- Open Graph (compartilhamento em redes sociais) -->
  <meta property="og:title" content={title} />
  <meta property="og:description" content={description} />
  <meta property="og:image" content={new URL(image, Astro.site)} />
  <meta property="og:url" content={canonicalURL} />

  <!-- Twitter Card -->
  <meta name="twitter:card" content="summary_large_image" />
  <meta name="twitter:title" content={title} />
  <meta name="twitter:description" content={description} />
  <meta name="twitter:image" content={new URL(image, Astro.site)} />
</head>

Assim, cada página terá metadados completos e exibirá um cartão atraente quando for compartilhada no Twitter e em outros aplicativos.

Gere um sitemap: mostre aos buscadores todas as suas páginas

É muito simples; basta um comando:

npx astro add sitemap

Depois, configure o domínio em astro.config.mjs:

export default defineConfig({
  site: 'https://seu-dominio.com',
  integrations: [sitemap()],
});

Após a implantação, o sitemap será gerado automaticamente em https://seu-dominio.com/sitemap-index.xml. Envie esse endereço ao Google Search Console e, depois de alguns dias, seus artigos poderão aparecer nas buscas.

Otimize o desempenho: velocidade também importa para SEO

O Astro já é rápido, mas há mais alguns ajustes úteis.

1. Otimização de imagens

Use o componente <Image> do Astro no lugar da tag <img> comum:

---

import { Image } from 'astro:assets';
import myImage from '../assets/photo.jpg';

---

<Image src={myImage} alt="Texto alternativo" />

Ele faz automaticamente o seguinte:

• Converte para formatos modernos, como WebP e AVIF
• Gera imagens responsivas em vários tamanhos
• Usa carregamento adiado

2. Minificação de CSS e JS

Railway - Plataforma de deploy moderna, sem ops complexas, no ar em minutos

Começar agora →Anúncio

O Astro minifica tudo automaticamente na compilação de produção, sem configuração adicional. Mesmo assim, remova dependências que não são usadas para reduzir o tamanho do projeto.

3. Otimização de fontes

Ao usar Google Fonts ou fontes personalizadas, adicione font-display: swap para impedir que o carregamento da fonte bloqueie a renderização:

@font-face {
  font-family: 'MyFont';
  src: url('/fonts/myfont.woff2') format('woff2');
  font-display: swap;
}

Depois desses ajustes, a nota do Lighthouse do seu blog deve permanecer acima de 95. No meu blog, apenas “Best Practices” perde alguns pontos por causa de scripts de terceiros; todos os outros indicadores chegam a 100.

Capítulo 6: implantação (escolha uma das duas plataformas gratuitas)

O código está pronto. Agora vem a parte mais empolgante: permitir que o mundo inteiro acesse seu blog. Vou apresentar duas plataformas de hospedagem gratuitas e fáceis de usar; basta escolher uma delas.

Opção 1: implantação na Vercel (recomendada para iniciantes)

A Vercel é minha principal recomendação porque oferece suporte nativo ao Astro e funciona sem configurações extras.

Etapa 1: envie o código ao GitHub

Se você ainda não criou um repositório, execute estes comandos na raiz do projeto:

git add .
git commit -m "Initial commit"
git branch -M main
git remote add origin https://github.com/seu-usuario/my-blog.git
git push -u origin main

Etapa 2: importe o projeto na Vercel

1. Acesse vercel.com e crie uma conta; entrar pelo GitHub é a opção mais prática
2. Clique em “New Project”
3. Escolha seu repositório my-blog
4. A Vercel reconhecerá automaticamente o Astro, sem exigir nenhuma alteração
5. Clique em “Deploy” e aguarde de 1 a 2 minutos

Etapa 3: acesse seu blog

Depois da implantação, a Vercel fornecerá um domínio xxx.vercel.app. Acesse-o e seu blog já estará no ar.

Conecte um domínio próprio (opcional)

Se você já tem um domínio, adicione-o nas configurações do projeto da Vercel e, no provedor do domínio, crie um registro CNAME apontando para o endereço indicado pela plataforma. A própria Vercel mostrará as instruções; é bem simples.

Armadilhas para iniciantes:

• Confira se o endereço site correto está definido em astro.config.mjs
• Configure variáveis de ambiente no painel da Vercel; não as escreva diretamente no código
• A primeira implantação pode levar 5 minutos, então tenha um pouco de paciência

Opção 2: implantação na Netlify (alternativa)

A Netlify é parecida com a Vercel, mas costuma ter acesso um pouco mais estável na China.

Etapa 1: envie o código ao GitHub

Assim como na Vercel, primeiro envie o projeto ao GitHub.

Etapa 2: importe o projeto na Netlify

1. Acesse netlify.com e crie uma conta
2. Clique em “Add new site” → “Import an existing project”
3. Conecte o GitHub e selecione seu repositório
4. Use estas configurações de compilação:
   • Build command: npm run build
   • Publish directory: dist
5. Clique em “Deploy”

Etapa 3: acesse seu blog

A plataforma também fornecerá um domínio xxx.netlify.app. Acesse-o para testar o site.

Qual das duas plataformas escolher?

Minha recomendação: comece pela Vercel e migre para a Netlify se o acesso na China ficar lento. As duas plataformas oferecem implantação automática: ao enviar código ao GitHub, elas compilam e atualizam o site por conta própria.

A mágica da implantação automática

Agora você só precisa:

1. Escrever o artigo localmente em um arquivo Markdown
2. Executar git add . → git commit -m "Novo artigo" → git push
3. Aguardar 2 minutos para que o artigo seja publicado automaticamente

Não é preciso entrar no servidor, compilar manualmente nem enviar arquivos. Essa é a força da implantação moderna; na primeira vez que usei, fiquei realmente impressionado.

Capítulo 7: problemas comuns e soluções (evite os tropeços que já enfrentei)

Esta parte reúne problemas reais que eu e outras pessoas da comunidade encontramos. Conhecê-los antes pode economizar bastante tempo.

Problema 1: os estilos do Tailwind não funcionam

Sintoma: você adiciona classes do Tailwind, mas nada muda na página.

Causa: os caminhos em content, dentro de tailwind.config.mjs, estão incorretos, e o Tailwind não encontra seus arquivos.

Solução:

Abra tailwind.config.mjs e confirme que o array content inclui todos os arquivos que precisam ser examinados:

export default {
  content: [
    './src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}',
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

Depois da alteração, reinicie o servidor de desenvolvimento: pressione Ctrl+C para interrompê-lo e execute npm run dev novamente.

Problema 2: erro “Invalid frontmatter” durante a compilação

Sintoma: o site funciona localmente, mas npm run build retorna um erro.

Causa: o frontmatter de um artigo Markdown está em formato incorreto ou não contém algum campo obrigatório.

Solução:

Abra src/content/config.ts, se existir, e confira quais campos são obrigatórios. Em geral, o template Blog exige:

---

title: 'Título do artigo'           # Obrigatório
description: 'Descrição do artigo'  # Obrigatório
pubDate: 'Dec 02 2025'              # Obrigatório; observe o formato da data
tags: ['Tag 1', 'Tag 2']            # Opcional

---

Essa é uma vantagem de Content Collections: os dados são validados durante a compilação, evitando problemas em produção.

Problema 3: erro 404 após a implantação, embora funcione localmente

Sintoma: tudo funciona no ambiente local, mas as páginas dos artigos retornam 404 na Vercel ou Netlify.

Causa: o caminho base está incorreto em astro.config.mjs ou site não foi configurado.

Alibaba Cloud - Escolha dos desenvolvedores, 15% de desconto exclusivo em Lighthouse

Ganhar 15% off →Anúncio

Solução:

Confira se o arquivo de configuração contém:

export default defineConfig({
  site: 'https://seu-dominio.com',  // Deve ser configurado
  // base: '/blog',  // Necessário apenas para implantação em um subdiretório
});

Se o blog não estiver em um subdiretório, como xxx.com/blog, não defina base.

Problema 4: as imagens carregam lentamente

Sintoma: as imagens dos artigos demoram para aparecer e prejudicam a experiência.

Causa: o componente Image do Astro não está sendo usado ou os arquivos de imagem são grandes demais.

Solução:

1. Use o componente Image (recomendado):

---

import { Image } from 'astro:assets';

---

<Image src="/images/photo.jpg" alt="Descrição" width={800} height={600} />

2. Comprima as imagens: use TinyPNG ou Squoosh.app antes de enviá-las

3. Use uma CDN: hospede as imagens em um serviço como Cloudinary ou Imgur e faça referência ao link da CDN

Problema 5: blocos de código sem destaque de sintaxe

Sintoma: os blocos de código em Markdown aparecem como texto simples, sem cores.

Causa: nenhum tema foi configurado ou há um problema com o plugin Shiki.

Solução:

Configure o tema de destaque em astro.config.mjs:

export default defineConfig({
  markdown: {
    shikiConfig: {
      theme: 'github-dark',  // Ou 'dracula', 'nord' etc.
    },
  },
});

O template Blog normalmente já inclui o Shiki. Se ainda não funcionar, reinstale as dependências com rm -rf node_modules && npm install.

Problema 6: o servidor de desenvolvimento demora para iniciar

Sintoma: npm run dev leva muito tempo para ficar pronto.

Causa: há artigos demais ou plugins em excesso.

Solução:

• Exclua node_modules e package-lock.json e instale tudo novamente
• Remova plugins desnecessários
• Atualize para a versão mais recente do Astro com npm install astro@latest

A inicialização ficou bem mais rápida no Astro 5.x. Se você ainda usa a versão 4.x, vale atualizar.

Depois de falar de tantos problemas, é bem possível que você nunca encontre a maioria deles. Mas, se algo acontecer, volte a este capítulo para localizar a causa rapidamente. Eu perdi bastante tempo nessas armadilhas e espero que esta experiência ajude você.

Conclusão

Se você acompanhou o tutorial até aqui, parabéns! Agora tem um blog com Astro completo, rápido e pronto para uso. Vamos recapitular o que foi implementado:

✅ Sistema completo de blog: página inicial, lista de artigos, páginas individuais, tags e categorias e feed RSS
✅ Otimização de SEO: metatags, sitemap e melhorias de desempenho para facilitar a descoberta do conteúdo
✅ Implantação moderna: CI/CD automático; basta enviar o código, sem manter o servidor manualmente
✅ Excelente desempenho: nota acima de 95 no Lighthouse e carregamento inicial em 0,8 segundo, com uma ótima experiência para o usuário

Mais importante: você entendeu a ideia central do Astro — prioridade para o conteúdo e desempenho acima de tudo. Essa abordagem serve não apenas para blogs, mas também para outros projetos de sites estáticos.

O que fazer agora?

Aja imediatamente (não adie):

• Reserve 1 hora agora e refaça o processo enquanto consulta este artigo
• Escreva e publique o primeiro artigo real do blog, mesmo que seja apenas um conteúdo de teste
• Compartilhe com amigos ou nas redes sociais e peça opiniões

Recursos avançados (adicione aos poucos):

• Sistema de comentários: integre Giscus, baseado no GitHub Discussions, ou Disqus
• Busca: use Algolia DocSearch ou Pagefind para implementar a busca interna
• Modo escuro: adicione um botão de troca de tema para tornar a leitura noturna mais confortável
• Estatísticas de leitura: integre Google Analytics ou Plausible, que é mais favorável à privacidade
• Navegação para o artigo anterior e o próximo: fortaleça a ligação entre os conteúdos

Recursos de aprendizado (aprofunde-se no Astro):

• Documentação oficial do Astro — a fonte de aprendizado mais confiável, com versão em chinês
• Site chinês do Astro — documentação e recursos mantidos pela comunidade chinesa
• Astro Paper — um excelente template de blog com ótimo SEO
• Discussões do Astro no GitHub — espaço para pedir ajuda e compartilhar experiências

Participe da comunidade (não faça tudo sozinho):

• Discord do Astro — o Discord oficial, bastante ativo
• Pesquise “awesome-astro” no GitHub para encontrar muitas coleções de bons recursos
• Compartilhe o link do seu blog no canal “Showcase” da comunidade Astro para receber comentários e sugestões

Uma última observação

Ao criar um blog, a tecnologia é apenas o primeiro passo. O mais importante é continuar escrevendo. Já vi muita gente passar uma semana ajustando o framework, publicar dois artigos e nunca mais atualizar o site. O Astro reduz ao mínimo a barreira técnica; o restante depende da sua disposição para produzir conteúdo com constância.

Se encontrar problemas durante a prática:

1. Consulte primeiro a seção “Troubleshooting” da documentação oficial do Astro
2. Pesquise palavras-chave nas Issues do repositório no GitHub
3. Faça uma pergunta no Discord do Astro, principalmente em inglês, embora também exista um canal em chinês

Não tenha medo de errar. Eu também precisei de três dias de tentativas até colocar meu primeiro blog Astro no ar. Depois de aprender, porém, a manutenção ficou muito mais simples.

Agora abra seu terminal e comece a criar seu blog com Astro! 💫