Como criar um blog com Astro e GitHub Pages

O que é o Astro?

O Astro é um framework web moderno, otimizado para sites focados em conteúdo como blogs, documentação e portfólios. A grande diferença dele para frameworks como Next.js ou Nuxt é que o Astro envia zero JavaScript por padrão — seu site é HTML puro, super rápido.

Estrutura de um projeto Astro

Quando você cria um projeto Astro, a estrutura de pastas é assim:

meu-blog/
├── public/          # Arquivos estáticos (fontes, imagens, favicon)
├── src/
│   ├── components/  # Componentes reutilizáveis (.astro)
│   ├── content/     # Conteúdo do blog (posts em .md/.mdx)
│   │   ├── blog/    # Posts do blog
│   │   └── authors/ # Perfis de autores
│   ├── layouts/     # Templates de página
│   ├── pages/       # Rotas do site (cada arquivo = uma página)
│   └── styles/      # CSS global
├── astro.config.ts  # Configuração do Astro
├── package.json     # Dependências
└── tsconfig.json    # Configuração TypeScript

Como funciona o conteúdo?

Content Collections

O Astro usa o conceito de Content Collections — coleções tipadas de conteúdo. No nosso blog, temos três coleções:

• blog — posts do blog (arquivos .md ou .mdx)
• authors — perfis de autores
• projects — projetos para o portfólio

Cada coleção tem um schema definido com Zod, que valida o frontmatter automaticamente:

1
const blog = defineCollection({
2
  loader: glob({ pattern: '**/*.{md,mdx}', base: './src/content/blog' }),
3
  schema: ({ image }) =>
4
    z.object({
5
      title: z.string(),
6
      description: z.string(),
7
      date: z.coerce.date(),
8
      tags: z.array(z.string()).optional(),
9
      authors: z.array(z.string()).optional(),
10
      draft: z.boolean().optional(),
11
    }),
12
})

Escrevendo um post

Para criar um novo post, basta criar uma pasta dentro de src/content/blog/ com um arquivo index.mdx:

src/content/blog/
└── meu-primeiro-post/
    └── index.mdx

O conteúdo do arquivo usa frontmatter (metadados no topo entre ---) seguido do conteúdo em Markdown:

1
---
2
title: 'Meu Primeiro Post'
3
description: 'Uma descrição curta do post.'
4
date: 2026-02-13
5
tags: ['exemplo']
6
authors: ['fabricio']
7
---
8

9
Aqui começa o conteúdo do post em **Markdown**!

Usando MDX: Markdown com superpoderes

Arquivos .mdx permitem usar componentes dentro do Markdown. Por exemplo, este callout que você está vendo é um componente:

1
import Callout from '@/components/Callout.astro'
2

3
<Callout variant="warning">
4
  Cuidado com este trecho!
5
</Callout>

Tipos de callout disponíveis: note, tip, warning, danger, example, quote.

Deploy no GitHub Pages

Passo 1: Repositório no GitHub

Crie um repositório no GitHub (pode ser privado). O nosso está em:

1
https://github.com/fabricioctelles/blog.ft.ia.br

Passo 2: GitHub Actions (deploy automático)

O arquivo .github/workflows/deploy.yml configura o deploy automático. Toda vez que você faz git push na branch main, o GitHub:

1. Faz checkout do código
2. Instala dependências (npm ci)
3. Executa astro build
4. Publica os arquivos estáticos no GitHub Pages

Passo 3: Configurar o domínio personalizado

Para usar um domínio como blog.ft.ia.br:

1. No seu provedor DNS, crie um registro CNAME apontando para fabricioctelles.github.io
2. No GitHub, vá em Settings → Pages → Custom domain e configure blog.ft.ia.br
3. No repositório, o arquivo public/CNAME já contém o domínio

Passo 4: Ativar GitHub Pages

No repositório do GitHub:

1. Vá em Settings → Pages
2. Em Source, selecione GitHub Actions
3. Pronto! O deploy acontecerá automaticamente

Fluxo de trabalho diário

Para publicar um novo post, o processo é simples:

# 1. Criar a pasta do post
mkdir -p src/content/blog/nome-do-post

# 2. Criar o arquivo do post
# (edite o index.mdx com seu conteúdo)

# 3. Testar localmente
npm run dev
# Acesse http://localhost:1234

# 4. Publicar
git add .
git commit -m "novo post: Nome do Post"
git push
# Deploy automático em ~2 minutos!

Funcionalidades do template

Este template já vem com:

• Syntax highlighting — blocos de código com tema, numeração de linhas e seções colapsáveis
• KaTeX — renderização de fórmulas matemáticas ($E = mc^2$)
• Table of Contents — índice lateral automático baseado nos headings
• Tags — categorização de posts com navegação por tag
• RSS — feed RSS automático em /rss.xml
• Sitemap — mapa do site em /sitemap-index.xml
• SEO — meta tags, Open Graph e canonical URLs
• Dark mode — tema claro/escuro automático
• Responsivo — funciona perfeitamente em mobile
• Subposts — posts hierárquicos (parent/child)
• Múltiplos autores — suporte a vários autores por post

Próximos passos

Agora que você entende a estrutura, é hora de criar conteúdo! Nos próximos posts, vou explorar mais funcionalidades avançadas do Astro e como personalizar ainda mais o blog.