Post

Guia sobre como usar Jekyll com o tema Chirpy

Posted
By Gean Martins
14 min read
Guia sobre como usar Jekyll com o tema Chirpy

Sumário

  1. Introdução ao Jekyll e ao Tema Chirpy
  2. Instalação e Configuração
  3. Gerenciamento de Conteúdo com Chirpy
  4. Recursos de Formatação e Estilização
  5. Incorporando Mídia e Elementos Visuais
  6. Customização e Extensão do Tema
  7. Deploy e Publicação
  8. Troubleshooting e Resolução de Problemas
  9. Recursos Adicionais

Introdução ao Jekyll e ao Tema Chirpy

Bem-vindo a este guia avançado sobre a utilização do Jekyll em conjunto com o popular tema Chirpy. Este tutorial é projetado especificamente para usuários que já possuem familiaridade com os conceitos básicos do Jekyll e buscam aprofundar seus conhecimentos.

Pré-requisitos

Antes de começar, certifique-se de que você possui:

  • Conhecimento básico de Jekyll e sua estrutura de diretórios
  • Familiaridade com Markdown e Front Matter
  • Experiência básica com linha de comando
  • Docker instalado em seu sistema (recomendado)

O que é o Tema Chirpy?

O tema Chirpy eleva a experiência do Jekyll ao fornecer:

  • Design moderno e responsivo
  • Modo escuro/claro automático
  • Sistema de busca integrado
  • Suporte a comentários
  • Integração com MathJax e Mermaid
  • Otimização para SEO

Estrutura do Tutorial

Este tutorial está organizado em uma progressão lógica que permite implementar um site Jekyll/Chirpy completo do zero até a publicação, com foco em técnicas avançadas e melhores práticas.

Instalação e Configuração

Preparação do Ambiente

Método 1: Instalação Simplificada com Docker (Recomendado)

Para usuários que preferem um ambiente isolado e reproduzível:

1
2
3
4
5
6
7
8
9

# Criar diretório do projeto
mkdir meu-blog-chirpy
cd meu-blog-chirpy

# Clonar o tema Chirpy
git clone --depth 1 https://github.com/cotes2020/jekyll-theme-chirpy.git .

# Remover histórico git do tema (opcional)
rm -rf .git

Método 2: Instalação Local

Para usuários que preferem instalação direta no sistema:

Nota: Este método requer Ruby 3.0+ e Node.js 16+ instalados no sistema.

1
2
3
4
5
6

# Instalar dependências
bundle install
npm install

# Executar o site localmente
bundle exec jekyll serve

Configuração com Docker

Dockerfile Simplificado

Crie um Dockerfile na raiz do projeto:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

# Use imagem oficial do Jekyll
FROM jekyll/jekyll:4.2.2

# Definir diretório de trabalho
WORKDIR /srv/jekyll

# Copiar arquivos de dependências
COPY Gemfile* ./
COPY package*.json ./

# Instalar dependências Ruby e Node.js
RUN bundle install && \
    npm install

# Copiar código fonte
COPY . .

# Construir o site
RUN JEKYLL_ENV=production bundle exec jekyll build

# Expor porta
EXPOSE 4000

# Comando padrão
CMD ["bundle", "exec", "jekyll", "serve", "--host", "0.0.0.0"]

Docker Compose (Alternativa Recomendada)

Para um fluxo de desenvolvimento mais eficiente, crie docker-compose.yml:

1
2
3
4
5
6
7
8
9
10
11

version: '3.8'
services:
  jekyll:
    image: jekyll/jekyll:4.2.2
    command: jekyll serve --watch --force_polling --host 0.0.0.0
    ports:
      - "4000:4000"
    volumes:
      - .:/srv/jekyll
    environment:
      - JEKYLL_ENV=development

Primeira Execução

Usando Docker Compose

1
2
3
4
5
6

# Iniciar o ambiente de desenvolvimento
docker-compose up

# Em outro terminal, instalar dependências (primeira vez)
docker-compose exec jekyll bundle install
docker-compose exec jekyll npm install

Verificação da Instalação

  1. Acesse http://localhost:4000
  2. Verifique se o site carrega corretamente
  3. Teste a navegação entre páginas
  4. Verifique se o modo escuro/claro funciona

Dica: Se encontrar erros, consulte a seção Troubleshooting deste tutorial.

Configuração Inicial do _config.yml

Edite o arquivo _config.yml com suas informações:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

# Informações básicas do site
title: "Meu Blog Técnico"
tagline: "Compartilhando conhecimento sobre tecnologia"
description: "Blog pessoal sobre desenvolvimento, DevOps e tecnologias emergentes"
url: "https://meublog.com"
baseurl: ""

# Informações do autor
author:
  name: "Seu Nome"
  email: "seu@email.com"
  links:
    - https://github.com/seuusuario
    - https://linkedin.com/in/seuusuario

# Configurações do tema
theme_mode: # [light|dark]
avatar: "/assets/img/avatar.jpg"

# Configurações de comentários (opcional)
comments:
  active: utterances
  utterances:
    repo: "seuusuario/seurepositorio"
    issue_term: "pathname"

# Analytics (opcional)
google_analytics:
  id: "G-XXXXXXXXXX"

Gerenciamento de Conteúdo com Chirpy

Estrutura de Posts

Organização de Arquivos

O Chirpy segue a convenção padrão do Jekyll para posts. Você pode organizar seus arquivos de várias formas:

Estrutura Simples:

1
2
3
4

_posts/
├── 2025-01-15-meu-primeiro-post.md
├── 2025-01-20-tutorial-docker.md
└── 2025-02-01-deploy-automatico.md

Estrutura Organizada por Categorias:

1
2
3
4
5
6
7
8
9

_posts/
├── tutoriais/
│   ├── 2025-01-15-introducao-jekyll.md
│   └── 2025-01-20-configuracao-chirpy.md
├── devops/
│   ├── 2025-01-25-docker-compose.md
│   └── 2025-02-01-ci-cd-github.md
└── reviews/
    └── 2025-02-05-ferramentas-2025.md

Importante: A estrutura de pastas é apenas para organização. As URLs finais são determinadas pela configuração permalink em _config.yml.

Front Matter Avançado

Exemplo Completo

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

---
layout: post
title: "Guia Completo de Deploy com GitHub Actions"
date: 2025-01-15 14:30:00 -0300
last_modified_at: 2025-01-16 09:00:00 -0300
author: gean
categories: [DevOps, CI/CD]
tags: [github-actions, deploy, automation, docker]
pin: true
math: false
mermaid: true
image:
  path: /assets/img/posts/github-actions-cover.jpg
  lqip: data:image/webp;base64,UklGRpoAAABXRUJQVlA4WAoAAAAQAAAADwAABwAAQUxQSDIAAAARL0AmbZurmr57yyIiqE8oiG0bejIYEQTgqiDA9vqnsUSI6H+oAERp2HZ65qP/VIAWAFZQOCBCAAAA8AEAnQEqEAAIAAVAfCWkAALp8sF8rgRgAP7o9FDvMCkMde9PK7euH5M1m6VWoDXf2FkP3BqV0ZYbO6NA/VFIAAAA
  alt: "Fluxo de deploy automatizado com GitHub Actions"
excerpt: "Aprenda a configurar pipelines de deploy automatizado usando GitHub Actions, desde a configuração básica até estratégias avançadas de deployment."
description: "Tutorial completo sobre implementação de CI/CD com GitHub Actions para projetos Jekyll e aplicações web modernas."
toc: true
comments: true
---

Explicação dos Campos

Campos Obrigatórios:

  • layout: Sempre “post” para artigos
  • title: Título do post (usado em SEO)
  • date: Data de publicação (formato ISO 8601)

Campos Recomendados:

  • author: ID do autor (referencia _data/authors.yml)
  • categories: Máximo 2 categorias para melhor UX
  • tags: Tags relevantes (minúsculas, separadas por hífen)
  • excerpt: Resumo manual para listagens

Campos Opcionais:

  • pin: Fixa o post no topo da página inicial
  • math: Habilita MathJax para equações
  • mermaid: Habilita diagramas Mermaid
  • image: Configuração da imagem de destaque
  • toc: Controla exibição do sumário
  • comments: Controla seção de comentários

Gerenciamento de Autores

Configuração em _data/authors.yml

Crie o arquivo _data/authors.yml para centralizar informações dos autores:

1
2
3
4
5
6
7
8
9
10
11

gean:
  name: "Gean Martins"
  twitter: "geanmartins"
  url: "https://geanmartins.com"
  avatar: "/assets/img/authors/gean.jpg"

colaborador:
  name: "Nome do Colaborador"
  email: "colaborador@email.com"
  url: "https://colaborador.com"
  github: "colaborador"

Uso no Front Matter

1
2
3
4
5

# Post de autor único
author: gean

# Post com múltiplos autores
authors: [gean, colaborador]

Recursos de Formatação e Estilização

Elementos Básicos

Títulos e Estrutura

Use a hierarquia de títulos corretamente:

1
2
3
4
5

## Título Principal da Seção (H2)

### Subtítulo (H3)

#### Detalhes Específicos (H4)

Listas e Organização

Lista com marcadores:

  • Item principal
    • Subitem
    • Outro subitem
  • Segundo item principal

Lista numerada:

  1. Primeiro passo
  2. Segundo passo
    1. Subpasso A
    2. Subpasso B
  3. Terceiro passo

Lista de tarefas:

  • Tarefa concluída
  • Tarefa pendente
  • Outra tarefa pendente

Prompts e Alertas

O Chirpy oferece quatro tipos de alertas para destacar informações importantes:

Dica Útil: Use prompts para destacar informações importantes e melhorar a experiência de leitura.

Informação: Este é um bloco informativo para contexto adicional.

Atenção: Cuidado com este procedimento, pois pode causar problemas se executado incorretamente.

Perigo: Esta ação é irreversível e pode causar perda de dados.

Código e Sintaxe

Código Inline

Use código inline para comandos ou variáveis curtas dentro do texto.

Blocos de Código

Com especificação de linguagem:

1
2
3

# Comandos de terminal
docker-compose up -d
docker-compose logs -f

1
2
3
4
5
6
7

# Configuração YAML
version: '3.8'
services:
  app:
    image: nginx:alpine
    ports:
      - "80:80"

Com nome de arquivo:

1
2
3
4

# _config.yml
title: "Meu Blog"
description: "Descrição do blog"
url: "https://meublog.com"

Caminhos de Arquivo

Use a classe .filepath para destacar caminhos:

Edite o arquivo _config.yml na raiz do projeto.

Incorporando Mídia e Elementos Visuais

Gerenciamento de Imagens

Sintaxe Básica

1
2

![Descrição da imagem](/assets/img/exemplo.jpg)
_Legenda da imagem em itálico_

Controle de Tamanho

1
2

![Imagem redimensionada](/assets/img/exemplo.jpg){: width="600" height="400" }
_Imagem com dimensões específicas_

Posicionamento

Imagem centralizada (padrão):

1
2

![Imagem centralizada](/assets/img/exemplo.jpg)
_Legenda centralizada_

Imagem à esquerda:

1

![Imagem à esquerda](/assets/img/exemplo.jpg){: .left }

Imagem à direita:

1

![Imagem à direita](/assets/img/exemplo.jpg){: .right }

Nota: Evite usar legendas com imagens flutuantes (.left ou .right) pois pode causar problemas de layout.

Imagens para Modo Escuro/Claro

1
2

![Versão Clara](/assets/img/exemplo-claro.jpg){: .light }
![Versão Escura](/assets/img/exemplo-escuro.jpg){: .dark }

Sombra em Imagens

1
2

![Screenshot com sombra](/assets/img/screenshot.jpg){: .shadow }
_Screenshot de aplicação com efeito de sombra_

Matemática com MathJax

Habilite matemática no Front Matter:

1

math: true

Equações Inline

A fórmula da energia é $E = mc^2$.

Blocos de Equação

\[\begin{align} \nabla \times \vec{\mathbf{B}} -\, \frac1c\, \frac{\partial\vec{\mathbf{E}}}{\partial t} &= \frac{4\pi}{c}\vec{\mathbf{j}} \\ \nabla \cdot \vec{\mathbf{E}} &= 4 \pi \rho \\ \nabla \times \vec{\mathbf{E}}\, +\, \frac1c\, \frac{\partial\vec{\mathbf{B}}}{\partial t} &= \vec{\mathbf{0}} \\ \nabla \cdot \vec{\mathbf{B}} &= 0 \end{align}\]

Diagramas com Mermaid

Habilite Mermaid no Front Matter:

1

mermaid: true

Fluxograma

graph TD
    A[Início] --> B{Decisão}
    B -->|Sim| C[Ação 1]
    B -->|Não| D[Ação 2]
    C --> E[Fim]
    D --> E

Diagrama de Sequência

sequenceDiagram
    participant U as Usuário
    participant A as Aplicação
    participant D as Banco de Dados
    
    U->>A: Fazer login
    A->>D: Verificar credenciais
    D-->>A: Credenciais válidas
    A-->>U: Login realizado

Customização e Extensão do Tema

Personalização de Estilos

Sobrescrevendo Variáveis Sass

Crie o arquivo _sass/custom.scss:

1
2
3
4
5
6
7
8
9
10
11

// Cores personalizadas
$primary-color: #2196F3;
$link-color: #1976D2;
$text-color: #333333;

// Tipografia
$base-font-size: 16px;
$base-line-height: 1.6;

// Espaçamentos
$spacing-unit: 1rem;

CSS Customizado

Adicione estilos específicos no mesmo arquivo:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

// Componente customizado
.destaque-especial {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  color: white;
  padding: $spacing-unit;
  border-radius: 8px;
  margin: $spacing-unit 0;
}

// Customização de código
.highlight {
  border-radius: 6px;
  box-shadow: 0 2px 4px rgba(0,0,0,0.1);
}

Includes e Layouts

Criando Include Customizado

Crie _includes/botao-cta.html:

1
2
3
4
5
6
7
8
9

<div class="cta-button">
  <a href="{{ include.url | default: '#' }}" 
     class="btn btn-primary btn-lg"
     {% if include.target %}target="{{ include.target }}"{% endif %}>
    {{ include.texto | default: "Saiba Mais" }}
  </a>
</div>

Uso no post:

1
2
3

{% include botao-cta.html url="https://exemplo.com" texto="Acesse Agora" target="_blank" %}

Sobrescrevendo Layout

Para customizar um layout, copie o arquivo original de _layouts do tema para seu diretório local e modifique conforme necessário.

Plugins Jekyll

Adicionando Plugins

Edite o Gemfile:

1
2
3
4
5
6

group :jekyll_plugins do
  gem "jekyll-feed"
  gem "jekyll-seo-tag"
  gem "jekyll-sitemap"
  gem "jekyll-paginate"
end

Atualize _config.yml:

1
2
3
4
5
6
7
8
9

plugins:
  - jekyll-feed
  - jekyll-seo-tag
  - jekyll-sitemap
  - jekyll-paginate

# Configuração de paginação
paginate: 10
paginate_path: "/page:num/"

Deploy e Publicação

Preparação para Deploy

Build de Produção

1
2
3
4
5

# Usando Docker
docker-compose exec jekyll bundle exec jekyll build --destination _site

# Instalação local
JEKYLL_ENV=production bundle exec jekyll build

Verificação Pré-Deploy

  1. Teste todos os links internos
  2. Verifique imagens e assets
  3. Confirme configurações de SEO
  4. Teste responsividade

Opções de Hospedagem

GitHub Pages

Configuração automática:

  1. Crie repositório no GitHub
  2. Configure GitHub Pages nas configurações
  3. Use GitHub Actions para build automático

Arquivo .github/workflows/pages.yml:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51

name: Deploy Jekyll to Pages

on:
  push:
    branches: ["main"]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        
      - name: Setup Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.2'
          bundler-cache: true
          
      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v4
        
      - name: Build with Jekyll
        run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"
        env:
          JEKYLL_ENV: production
          
      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

Netlify

  1. Conecte seu repositório ao Netlify
  2. Configure build settings:
    • Build command: bundle exec jekyll build
    • Publish directory: _site
  3. Configure variáveis de ambiente se necessário

Vercel

  1. Importe projeto no Vercel
  2. Configure framework preset para Jekyll
  3. Deploy automático a cada push

Configuração de Domínio

Domínio Customizado

Para GitHub Pages:

  1. Adicione arquivo CNAME na raiz:
    1

    meudominio.com
  2. Configure DNS:
    1
2
3
4
5

    CNAME www meuusuario.github.io
A @ 185.199.108.153
A @ 185.199.109.153
A @ 185.199.110.153
A @ 185.199.111.153

Para Netlify/Vercel:

  • Configure através do painel administrativo
  • Adicione registros DNS conforme instruções da plataforma

Troubleshooting e Resolução de Problemas

Problemas Comuns de Build

Erro de Dependências

Problema: Bundler could not find compatible versions

Solução:

1
2
3
4
5
6

# Limpar cache do bundler
bundle clean --force

# Reinstalar dependências
rm Gemfile.lock
bundle install

Erro de Node.js

Problema: Error: Cannot find module

Solução:

1
2
3
4
5
6

# Limpar cache npm
npm cache clean --force

# Reinstalar dependências
rm -rf node_modules package-lock.json
npm install

Problemas de Renderização

Imagens não Carregam

Verificações:

  1. Caminho correto do arquivo
  2. Configuração baseurl em _config.yml
  3. Permissões de arquivo

CSS não Aplica

Verificações:

  1. Ordem de importação dos arquivos Sass
  2. Sintaxe correta do CSS/Sass
  3. Cache do navegador

Problemas de Performance

Site Lento

Otimizações:

  1. Comprimir imagens
  2. Minificar CSS/JS
  3. Usar CDN para assets
  4. Otimizar plugins

Build Demorado

Soluções:

  1. Usar --incremental em desenvolvimento
  2. Excluir arquivos desnecessários
  3. Otimizar plugins

Problemas de Deploy

GitHub Pages não Atualiza

Verificações:

  1. Status do GitHub Actions
  2. Configuração de branch
  3. Arquivo _config.yml válido

Netlify Build Falha

Soluções:

  1. Verificar logs de build
  2. Configurar variáveis de ambiente
  3. Ajustar configurações de Ruby/Node

Problemas de Interpretação Liquid

Jekyll Interpreta Código Jinja2/Ansible como Liquid

Problema: Jekyll pode interpretar blocos {% ... %} e {{ ... }} de outras linguagens (Jinja2, Ansible, etc.) como lógica Liquid, causando erros de build ou renderização incorreta.

Sintomas:

  • Erros de build com mensagens sobre tags Liquid desconhecidas
  • Conteúdo de código desaparece ou é renderizado incorretamente
  • Falhas ao processar documentação de outras ferramentas

Exemplo Problemático:

1
2
3
4
5
6
7
8

# Arquivo Ansible que causa problemas
- name: Deploy application
  template:
    src: app.conf.j2
    dest: /etc/app.conf
  vars:
    app_name: "{{ application_name }}"
    app_port: "{% if environment == 'prod' %}80{% else %}8080{% endif %}"

Solução 1: Escape Manual com Raw

Use {% raw %} e {% endraw %} para escapar blocos específicos:

Exemplo de template Jinja2:

1
2
3
4
5
6
7
8
9

- name: Configure service
  template:
    src: service.j2
    dest: /etc/service.conf
  vars:
    service_port: "{{ port | default(8080) }}"
    debug_mode: "{% if env == 'dev' %}true{% else %}false{% endif %}"

Solução 2: Alteração em Massa com Vim

Para arquivos com muitos blocos Jinja2/Ansible, use comandos vim para escape automático:

Escapar blocos {% ... %}:

1

:%s/{%\(\_.\{-}\)%}/{{ "{% raw " }}%}{%\1%}{{ "{% endraw " }}%}/g

Escapar blocos {{ ... }}:

1

:%s/{{\(\_.\{-}\)}}/{{ "{% raw " }}%}{{\1}}{{ "{% endraw " }}%}/g

Solução 3: Configuração Global

Para projetos com muito código Jinja2/Ansible, considere configurar exclusões no _config.yml:

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# _config.yml
markdown: kramdown
kramdown:
  input: GFM
  syntax_highlighter: rouge
  syntax_highlighter_opts:
    block:
      line_numbers: false

# Excluir arquivos específicos do processamento
exclude:
  - ansible/
  - templates/
  - "*.j2"

Solução 4: Uso de Includes para Código Complexo

Para documentação extensa de outras ferramentas, considere usar includes:

1
2
3
4
5
6
7
8
9

<!-- _includes/ansible-example.html -->
<pre><code class="language-yaml">
- name: Example task
  template:
    src: "{{ item.src }}"
    dest: "{{ item.dest }}"
  loop:
    - { src: "app.j2", dest: "/etc/app.conf" }
</code></pre>

Uso no post:

1
2

Exemplo de playbook Ansible:
{% include ansible-example.html %}

Dicas Importantes:

Atenção: Sempre teste o build após adicionar código de outras linguagens de template.

Dica: Use syntax highlighting específico (yaml, jinja2) para melhor apresentação visual.

Importante: O escape com raw afeta apenas a interpretação Liquid, não o syntax highlighting.

Recursos Adicionais

Documentação Oficial

Ferramentas Úteis

  • Editores: VS Code com extensões Jekyll
  • Imagens: TinyPNG para compressão
  • Ícones: Font Awesome, Feather Icons
  • Analytics: Google Analytics, Plausible

Comunidade e Suporte

Próximos Passos

  1. Explore temas relacionados: Outros temas Jekyll
  2. Aprenda sobre JAMstack: Conceitos modernos de desenvolvimento web
  3. Automatize workflows: CI/CD avançado
  4. Otimize para SEO: Técnicas avançadas de otimização

Conclusão: Este tutorial fornece uma base sólida para criar e manter um blog profissional com Jekyll e Chirpy. Continue experimentando e personalizando conforme suas necessidades específicas.

Jekyll, Chirpy, Blog
Jekyll Chirpy Docker Front-Matter Markdown
This post is licensed under CC BY 4.0 by the author.