Murad Library
Info
Murad LibraryREF-0327MD

Tutorial completo de Jekyll

Catalogued
Reading
21 min read

Gerador de sites estáticos para blogs, documentação, zines, bibliotecas digitais e páginas pessoais

Compilado por Pablo Murad - 2026

1. O que é Jekyll?

Jekyll é um gerador de sites estáticos. Ele transforma arquivos simples — principalmente Markdown, HTML, Liquid, CSS e dados em YAML/JSON/CSV — em um site estático pronto para ser publicado.

Em vez de rodar um sistema dinâmico como WordPress, Drupal ou Ghost, o Jekyll gera uma pasta final com arquivos HTML, CSS, JavaScript e imagens. Essa pasta pode ser hospedada em praticamente qualquer servidor web: Caddy, Nginx, Apache, GitHub Pages, Netlify, Cloudflare Pages, Vercel ou até hospedagem FTP simples.

A ideia central é:

Markdown + templates + configurações
        ↓
      Jekyll
        ↓
HTML/CSS/JS estático pronto para publicar

O site oficial resume bem: Markdown, Liquid, HTML e CSS entram; sites estáticos saem prontos para deploy.

2. Para que serve Jekyll?

Jekyll é especialmente bom para:

  • blogs pessoais;
  • sites editoriais;
  • documentação técnica;
  • páginas institucionais simples;
  • zines digitais;
  • bibliotecas estáticas;
  • portfólios;
  • sites de projetos open source;
  • manuais;
  • wikis pequenas;
  • páginas de cursos;
  • catálogos de textos, artigos ou livros;
  • sites sem banco de dados.

Ele é péssimo para algumas coisas também. Não tente usar Jekyll como se fosse um WordPress completo com painel de administração, login de usuários, comentários dinâmicos e carrinho de compra. Dá para integrar serviços externos, mas o núcleo dele é estático.

Resumo seco: Jekyll é excelente quando o conteúdo muda por arquivo e Git. É ruim quando você precisa de interação dinâmica pesada no servidor.

3. Como Jekyll funciona

O funcionamento básico é simples:

  1. Você escreve páginas e posts em .md ou .html.
  2. Define metadados no início do arquivo usando front matter.
  3. Cria layouts em HTML usando Liquid.
  4. Configura o site no arquivo _config.yml.
  5. Roda o build.
  6. Jekyll gera a pasta _site.
  7. Você publica o conteúdo da pasta _site.

Exemplo de post:

---
layout: post
title: "Meu primeiro post"
date: 2026-06-17
categories: tecnologia servidores
---

Este é meu primeiro post escrito em Markdown usando Jekyll.

Depois do build, isso vira uma página HTML final.

4. Principais vantagens

4.1. Não precisa de banco de dados

Jekyll não usa MySQL, PostgreSQL, MongoDB ou qualquer banco para funcionar. O conteúdo fica em arquivos.

Isso reduz manutenção, ataque, custo e dor de cabeça.

4.2. É rápido

Como o resultado final é HTML estático, o servidor só entrega arquivos prontos. Não precisa executar PHP, consultar banco, montar página em tempo real ou carregar CMS pesado.

4.3. É seguro por padrão

Menos partes móveis significam menos superfície de ataque. Sem painel administrativo online, sem banco exposto, sem plugins PHP aleatórios, sem login de admin para ser atacado.

Isso não significa segurança absoluta. Mas comparado a um CMS dinâmico mal cuidado, é muito mais simples de proteger.

4.4. É ótimo com Git

Cada alteração no site pode ser versionada. Você consegue saber quem mudou o quê, quando mudou e reverter alterações.

4.5. É excelente para Markdown

Se você gosta de escrever em Markdown, Jekyll é natural. Posts, páginas e documentação ficam legíveis mesmo fora do site.

4.6. Hospedagem simples

Como ele gera arquivos estáticos, você pode publicar em:

  • GitHub Pages;
  • Cloudflare Pages;
  • Netlify;
  • Vercel;
  • VPS com Caddy;
  • VPS com Nginx;
  • Apache;
  • hospedagem FTP comum;
  • servidor local;
  • IPFS ou soluções mais experimentais.

5. Principais desvantagens

5.1. Depende do ecossistema Ruby

Jekyll é feito em Ruby. Isso não é um problema se você conhece Ruby, Bundler e gems. Mas para quem vem de Node.js ou Python, pode parecer meio estranho no começo.

5.2. Build pode ficar lento em sites grandes

Sites pequenos e médios funcionam muito bem. Mas se você tiver milhares de páginas, muitas coleções, muitos filtros Liquid e plugins pesados, o build pode ficar lento.

5.3. Não tem painel administrativo nativo

Você escreve em arquivos. Isso é ótimo para programadores, escritores técnicos e gente que gosta de Git. Mas é ruim para equipe não técnica que quer editar tudo por painel visual.

5.4. Plugins têm limitações no GitHub Pages

O GitHub Pages tem suporte a Jekyll, mas nem todo plugin customizado roda direto no build do GitHub. Se você precisar de plugins não suportados, o caminho correto é gerar o site localmente ou via GitHub Actions e publicar os arquivos prontos.

5.5. Não é app web dinâmico

Jekyll não substitui Laravel, Django, Rails, Express ou Next.js quando você precisa de backend real.

6. Instalação no Debian/Ubuntu

No Debian 12 ou Ubuntu, você pode instalar Ruby, ferramentas de compilação e Bundler.

sudo apt update
sudo apt install ruby-full build-essential zlib1g-dev

Depois instale Jekyll e Bundler:

gem install jekyll bundler

Verifique:

jekyll -v
bundle -v

Dependendo do seu ambiente, pode ser melhor configurar instalação local de gems no usuário, evitando usar sudo gem install. Em servidor de produção, isso costuma ser mais limpo.

7. Criando um site novo

Crie um novo projeto:

jekyll new meu-site
cd meu-site

Instale dependências:

bundle install

Rode localmente:

bundle exec jekyll serve

Abra no navegador:

http://localhost:4000

Com recarregamento automático:

bundle exec jekyll serve --livereload

Se você estiver usando Ruby 3 ou superior e aparecer erro relacionado ao webrick, rode:

bundle add webrick
bundle exec jekyll serve

8. Estrutura básica de um projeto Jekyll

Um projeto Jekyll pode ter esta aparência:

meu-site/
├── _config.yml
├── _posts/
│   └── 2026-06-17-meu-primeiro-post.md
├── _layouts/
│   ├── default.html
│   └── post.html
├── _includes/
│   ├── header.html
│   └── footer.html
├── _data/
│   └── menu.yml
├── assets/
│   ├── css/
│   ├── js/
│   └── img/
├── index.md
├── about.md
├── Gemfile
└── _site/

_config.yml

Arquivo principal de configuração.

Exemplo:

title: Biblioteca Arcana
description: Textos, estudos e compêndios
url: "https://exemplo.com"
baseurl: ""

markdown: kramdown
theme: minima

plugins:
  - jekyll-feed
  - jekyll-seo-tag

_posts/

Pasta dos posts do blog. Os arquivos precisam seguir o padrão:

AAAA-MM-DD-titulo-do-post.md

Exemplo:

2026-06-17-caddy-e-jekyll.md

_layouts/

Layouts HTML usados por páginas e posts.

Exemplo de layout:

<!doctype html>
<html lang="pt-BR">
<head>
  <meta charset="utf-8">
  <title>{{ page.title }} - {{ site.title }}</title>
</head>
<body>
  {% include header.html %}

  <main>
    {{ content }}
  </main>

  {% include footer.html %}
</body>
</html>

_includes/

Pedaços reutilizáveis de HTML.

Exemplo:

<header>
  <h1>{{ site.title }}</h1>
  <nav>
    <a href="/">Início</a>
    <a href="/sobre/">Sobre</a>
  </nav>
</header>

_data/

Arquivos de dados em YAML, JSON ou CSV.

Exemplo _data/menu.yml:

- title: Início
  url: /
- title: Sobre
  url: /sobre/
- title: Arquivo
  url: /arquivo/

Uso no template:

{% for item in site.data.menu %}
  <a href="{{ item.url }}">{{ item.title }}</a>
{% endfor %}

_site/

Pasta gerada pelo Jekyll. É o resultado final do build.

Atenção: normalmente você não edita nada dentro de _site, porque essa pasta é recriada pelo Jekyll.

9. Front matter

O front matter é o bloco de metadados no topo do arquivo.

Exemplo:

---
layout: page
title: Sobre
permalink: /sobre/
---

Texto da página Sobre.

Campos comuns:

layout: post
title: "Título do texto"
date: 2026-06-17
categories: servidores linux
tags: [jekyll, markdown, web]
permalink: /textos/jekyll/
published: true

O front matter permite controlar como cada página será renderizada.

10. Páginas versus posts

Páginas

São conteúdos fixos, como:

  • Sobre;
  • Contato;
  • Manifesto;
  • Biblioteca;
  • Projetos;
  • Currículo;
  • Índice.

Exemplo sobre.md:

---
layout: page
title: Sobre
permalink: /sobre/
---

Este é um site criado com Jekyll.

Posts

São conteúdos com data, normalmente usados em blog.

Exemplo _posts/2026-06-17-meu-post.md:

---
layout: post
title: "Meu post"
date: 2026-06-17
categories: diario
---

Conteúdo do post.

11. Liquid: o motor de templates

Jekyll usa Liquid como linguagem de template.

Exibir variável:

{{ page.title }}

Condição:

{% if page.author %}
  <p>Autor: {{ page.author }}</p>
{% endif %}

Loop:

{% for post in site.posts %}
  <article>
    <h2><a href="{{ post.url }}">{{ post.title }}</a></h2>
    <p>{{ post.excerpt }}</p>
  </article>
{% endfor %}

Filtros:

{{ page.date | date: "%d/%m/%Y" }}
{{ page.title | upcase }}
{{ content | strip_html | truncate: 160 }}

Liquid é simples, mas dá para fazer bastante coisa: listagens, menus, páginas de arquivo, filtros por categoria, cards de conteúdo e templates reutilizáveis.

12. Criando uma página inicial

Exemplo de index.md:

---
layout: default
title: Início
---

# Bem-vindo

Este site foi criado com Jekyll.

## Últimos posts

{% for post in site.posts limit:5 %}
- [{{ post.title }}]({{ post.url }}) — {{ post.date | date: "%d/%m/%Y" }}
{% endfor %}

Sim, você pode usar Liquid dentro de Markdown quando o arquivo tem front matter.

13. Criando um blog

Crie a pasta _posts e adicione posts:

_posts/2026-06-17-primeiro-post.md
_posts/2026-06-18-segundo-post.md

Exemplo de listagem de posts em blog.md:

---
layout: page
title: Blog
permalink: /blog/
---

# Blog

{% for post in site.posts %}
## [{{ post.title }}]({{ post.url }})

{{ post.date | date: "%d/%m/%Y" }}

{{ post.excerpt }}
{% endfor %}

14. Categorias e tags

No post:

categories: servidores linux
tags: [caddy, jekyll, nginx]

Você pode listar categorias:

{% for category in site.categories %}
  <h2>{{ category[0] }}</h2>
  <ul>
    {% for post in category[1] %}
      <li><a href="{{ post.url }}">{{ post.title }}</a></li>
    {% endfor %}
  </ul>
{% endfor %}

E tags:

{% for tag in site.tags %}
  <h2>{{ tag[0] }}</h2>
  <ul>
    {% for post in tag[1] %}
      <li><a href="{{ post.url }}">{{ post.title }}</a></li>
    {% endfor %}
  </ul>
{% endfor %}

15. Collections: conteúdo além de posts

Collections são uma das partes mais úteis do Jekyll. Elas permitem criar tipos de conteúdo próprios.

Exemplos:

  • livros;
  • cursos;
  • autores;
  • documentos;
  • receitas;
  • fotografias;
  • projetos;
  • verbetes;
  • edições de zine;
  • compêndios.

No _config.yml:

collections:
  livros:
    output: true
    permalink: /livros/:name/
  cursos:
    output: true
    permalink: /cursos/:name/

Crie arquivos:

_livros/kybalion.md
_livros/corpus-hermeticum.md
_cursos/introducao-linux.md

Exemplo _livros/kybalion.md:

---
title: "O Kybalion"
autor: "Três Iniciados"
ano: 1908
layout: livro
---

Descrição do livro.

Listagem:

{% for livro in site.livros %}
  <h2><a href="{{ livro.url }}">{{ livro.title }}</a></h2>
  <p>{{ livro.autor }} — {{ livro.ano }}</p>
{% endfor %}

Collections são perfeitas para transformar Jekyll em catálogo, biblioteca digital ou base de conhecimento.

16. Data files: dados separados do conteúdo

A pasta _data permite usar dados estruturados.

Exemplo _data/autores.yml:

- nome: Fulcanelli
  area: Alquimia
  slug: fulcanelli

- nome: Eliphas Levi
  area: Ocultismo
  slug: eliphas-levi

Uso:

{% for autor in site.data.autores %}
  <h2>{{ autor.nome }}</h2>
  <p>{{ autor.area }}</p>
{% endfor %}

Isso é útil para menus, catálogos, listas de links, membros, produtos, cursos e metadados.

17. Temas

Jekyll suporta temas, muitos distribuídos como gems Ruby.

Um tema pode incluir:

  • layouts;
  • includes;
  • CSS/Sass;
  • componentes visuais;
  • estrutura base.

Exemplo no Gemfile:

gem "minima"

No _config.yml:

theme: minima

Instale:

bundle install

Rode:

bundle exec jekyll serve

Você pode sobrescrever partes do tema criando arquivos com o mesmo caminho no seu projeto. Por exemplo, se o tema tem _layouts/default.html, você pode criar o seu próprio _layouts/default.html e ele passa a ter prioridade.

Onde encontrar temas

  • Site oficial do Jekyll;
  • GitHub;
  • RubyGems;
  • coleções como Jamstack Themes;
  • repositórios de temas open source.

Cuidado: tema bonito abandonado é dívida técnica com maquiagem.

18. Plugins e addons

Jekyll tem sistema de plugins. Plugins podem criar filtros, tags, geradores de páginas, hooks e funcionalidades extras.

Plugins comuns:

jekyll-feed

Gera feed RSS/Atom.

plugins:
  - jekyll-feed

jekyll-seo-tag

Adiciona metatags úteis para SEO e compartilhamento social.

No layout:

{% seo %}

jekyll-sitemap

Gera sitemap XML.

plugins:
  - jekyll-sitemap

jekyll-paginate

Adiciona paginação simples para posts.

plugins:
  - jekyll-paginate

paginate: 10
paginate_path: "/blog/page:num/"

jekyll-archives

Ajuda a gerar páginas de arquivo por categoria, tag, ano ou mês.

jekyll-redirect-from

Cria redirecionamentos a partir de URLs antigas.

No front matter:

redirect_from:
  - /url-antiga/

jekyll-scholar

Útil para sites acadêmicos com bibliografia BibTeX.

jekyll_picture_tag

Ajuda com imagens responsivas.

jekyll-toc

Gera sumário automático de headings.

jekyll-last-modified-at

Permite mostrar última modificação de uma página com base no Git.

jekyll-compose

Ajuda a criar posts, drafts e páginas via linha de comando.

Exemplo:

bundle exec jekyll post "Meu novo post"

Atenção ao GitHub Pages

O GitHub Pages não executa qualquer plugin arbitrário no modo padrão de build. Se você depende de plugins customizados ou não suportados, use uma destas opções:

  1. gerar o site localmente e publicar _site;
  2. usar GitHub Actions para buildar e publicar;
  3. usar Netlify, Cloudflare Pages ou outro serviço que rode seu build completo;
  4. hospedar em VPS com pipeline próprio.

19. Criando seu próprio plugin

Você pode criar plugins Ruby dentro da pasta _plugins.

Exemplo simples de filtro:

# _plugins/gritar.rb
module Jekyll
  module Gritar
    def gritar(input)
      input.upcase
    end
  end
end

Liquid::Template.register_filter(Jekyll::Gritar)

Uso:

{{ "olá mundo" | gritar }}

Resultado:

OLÁ MUNDO

Isso é poderoso, mas tenha cuidado. Plugin customizado prende seu site a um ambiente de build específico. No GitHub Pages padrão, isso pode não funcionar.

20. Assets: CSS, JS e imagens

Você pode manter arquivos estáticos em assets/.

Exemplo:

assets/css/style.css
assets/js/main.js
assets/img/logo.png

No layout:

<link rel="stylesheet" href="{{ '/assets/css/style.css' | relative_url }}">
<script src="{{ '/assets/js/main.js' | relative_url }}"></script>

Para imagens:

![Descrição da imagem](/assets/img/foto.jpg)

Ou:

<img src="{{ '/assets/img/foto.jpg' | relative_url }}" alt="Descrição">

21. Sass/SCSS

Jekyll pode processar Sass/SCSS.

Exemplo assets/css/style.scss:

---
---

$cor: #222;

body {
  color: $cor;
  font-family: system-ui, sans-serif;
}

O front matter vazio no topo faz o Jekyll processar o arquivo.

22. Permalinks

Permalinks controlam as URLs finais.

No _config.yml:

permalink: /:categories/:year/:month/:day/:title/

Ou por página/post:

permalink: /meu-link-personalizado/

Isso permite separar a estrutura de arquivos da estrutura pública do site.

23. Drafts

Você pode criar rascunhos em _drafts/.

_drafts/meu-rascunho.md

Rodar incluindo drafts:

bundle exec jekyll serve --drafts

Rascunhos não precisam ter data no nome.

24. Build de produção

Para gerar o site:

JEKYLL_ENV=production bundle exec jekyll build

O resultado fica em:

_site/

É essa pasta que você publica.

25. Hospedando com Caddy

Suponha que você gerou o site e copiou _site para:

/var/www/jekyll-site

Caddyfile:

meusite.com {
    root * /var/www/jekyll-site
    file_server
}

Depois:

sudo systemctl reload caddy

O Caddy cuida do HTTPS automático se o domínio estiver apontando corretamente para o servidor e as portas 80/443 estiverem acessíveis.

Esse é um combo muito bom:

Jekyll gera o site
Caddy hospeda o site

26. Hospedando com Nginx

Exemplo básico:

server {
    listen 80;
    server_name meusite.com;

    root /var/www/jekyll-site;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }
}

Depois você pode usar Certbot ou outro método para HTTPS.

27. Publicando no GitHub Pages

O GitHub Pages tem suporte nativo a Jekyll.

Fluxo simples:

git init
git add .
git commit -m "Site Jekyll inicial"
git branch -M main
git remote add origin git@github.com:usuario/repositorio.git
git push -u origin main

Depois, no GitHub:

  1. vá em Settings;
  2. abra Pages;
  3. escolha a branch;
  4. publique.

Para sites com plugins além do suportado, prefira GitHub Actions ou publique a pasta gerada.

28. Publicando via GitHub Actions

Um fluxo moderno é deixar o GitHub Actions gerar o site.

Exemplo conceitual:

name: Build Jekyll

on:
  push:
    branches: [main]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.3'
          bundler-cache: true
      - run: bundle exec jekyll build

Para deploy real no GitHub Pages, Netlify, Cloudflare Pages ou VPS, você adicionaria os passos correspondentes.

29. Publicando em VPS com rsync

No servidor:

sudo mkdir -p /var/www/meu-site
sudo chown -R $USER:www-data /var/www/meu-site

Localmente:

JEKYLL_ENV=production bundle exec jekyll build
rsync -avz --delete _site/ usuario@servidor:/var/www/meu-site/

Caddyfile:

meusite.com {
    root * /var/www/meu-site
    file_server
}

30. Integração com Jenkins

Jenkins pode automatizar o build e deploy de um site Jekyll.

Pipeline conceitual:

pipeline {
    agent any

    stages {
        stage('Instalar dependências') {
            steps {
                sh 'bundle install'
            }
        }

        stage('Build') {
            steps {
                sh 'JEKYLL_ENV=production bundle exec jekyll build'
            }
        }

        stage('Deploy') {
            steps {
                sh 'rsync -avz --delete _site/ usuario@servidor:/var/www/meu-site/'
            }
        }
    }
}

Aqui fica clara a diferença:

Jekyll gera o site.
Jenkins automatiza o build/deploy.
Caddy ou Nginx hospedam o resultado.

31. Ideias legais para usar Jekyll

31.1. Blog pessoal minimalista

Escreva tudo em Markdown, versione no Git e publique com Caddy.

31.2. Biblioteca digital

Use collections para livros, autores e temas.

_livros/
_autores/
_temas/

31.3. Zine digital

Cada edição pode ser uma collection ou uma categoria.

_edicoes/001.md
_edicoes/002.md

31.4. Documentação de projetos

Perfeito para documentar scripts, APIs, projetos internos e ferramentas.

31.5. Site de curso

Use collections para aulas:

_aulas/01-introducao.md
_aulas/02-instalacao.md
_aulas/03-projeto-final.md

31.6. Catálogo de comandos

Crie uma base de conhecimento com comandos Linux, Docker, Caddy, Git etc.

31.7. Diário técnico

Um log de aprendizado, problemas resolvidos, configurações e tutoriais.

31.8. Site de notas pessoais

Com tags, categorias e busca via JavaScript, Jekyll vira um pequeno sistema de notas público.

32. Busca em site Jekyll

Como Jekyll é estático, não há busca dinâmica no servidor por padrão.

Opções:

  1. busca client-side com JavaScript;
  2. Lunr.js;
  3. Pagefind;
  4. Algolia DocSearch;
  5. busca externa do Google;
  6. endpoint próprio separado.

Para site pequeno/médio, Pagefind ou Lunr.js funcionam bem.

33. Comentários em blog Jekyll

Jekyll não tem comentários nativos dinâmicos. Opções:

  • Disqus;
  • Giscus, usando GitHub Discussions;
  • Utterances, usando GitHub Issues;
  • Comentários via formulário externo;
  • não usar comentários.

Minha opinião: para site pessoal ou técnico, Giscus costuma ser uma opção mais limpa que Disqus.

34. Formulários

Jekyll não processa formulário sozinho. Você precisa de serviço externo ou backend.

Opções:

  • Formspree;
  • Netlify Forms;
  • Cloudflare Workers;
  • endpoint próprio em Flask/FastAPI/Node;
  • Google Forms incorporado.

35. SEO básico

Boas práticas:

  • use URLs limpas;
  • configure title e description;
  • use jekyll-seo-tag;
  • gere sitemap;
  • gere feed;
  • use headings corretamente;
  • defina canonical_url se necessário;
  • otimize imagens;
  • escreva descrições úteis.

Exemplo _config.yml:

title: Meu Site
description: Textos sobre tecnologia e servidores
url: "https://meusite.com"
plugins:
  - jekyll-seo-tag
  - jekyll-sitemap
  - jekyll-feed

No layout:

{% seo %}

36. Performance

Jekyll já gera site rápido por natureza, mas você pode melhorar:

  • comprimir imagens;
  • usar CSS pequeno;
  • evitar JavaScript desnecessário;
  • usar cache no Caddy/Nginx/CDN;
  • usar fontes locais;
  • gerar imagens responsivas;
  • minificar assets se necessário;
  • usar CDN com cuidado.

Não transforme um site estático em uma árvore de Natal com 3 MB de JavaScript. Seria burrice técnica.

37. Segurança

Jekyll reduz riscos porque não há backend dinâmico no site final. Ainda assim:

  • mantenha Ruby/gems atualizados;
  • não instale plugin abandonado sem ler;
  • revise dependências;
  • proteja o servidor web;
  • use HTTPS;
  • configure headers de segurança;
  • cuidado com scripts externos;
  • cuidado com formulários de terceiros;
  • não publique arquivos secretos.

Nunca coloque .env, chaves API ou credenciais dentro do repositório público.

38. Arquivo .gitignore recomendado

_site/
.sass-cache/
.jekyll-cache/
.jekyll-metadata
.bundle/
vendor/
.env

39. Comandos úteis

Criar site:

jekyll new meu-site

Rodar local:

bundle exec jekyll serve

Rodar com live reload:

bundle exec jekyll serve --livereload

Gerar produção:

JEKYLL_ENV=production bundle exec jekyll build

Limpar build:

bundle exec jekyll clean

Verificar versão:

bundle exec jekyll -v

40. Fluxo de trabalho recomendado

Para um projeto sério:

1. Escrever conteúdo em Markdown
2. Testar localmente com bundle exec jekyll serve
3. Commit no Git
4. Build automatizado via GitHub Actions/Jenkins
5. Deploy para VPS/GitHub Pages/Cloudflare Pages
6. Servir com Caddy ou CDN

Para projeto pessoal simples:

1. Escrever Markdown
2. bundle exec jekyll build
3. rsync _site/ para a VPS
4. Caddy serve o site

41. Quando usar Jekyll

Use Jekyll quando:

  • você gosta de Markdown;
  • o conteúdo é mais importante que interatividade;
  • você quer site rápido e simples;
  • você quer versionar tudo com Git;
  • você quer fugir de banco de dados;
  • você quer publicar documentação;
  • você quer site pessoal, blog, zine ou biblioteca;
  • você quer hospedar barato.

42. Quando não usar Jekyll

Não use Jekyll quando:

  • você precisa de painel administrativo completo;
  • usuários precisam fazer login;
  • o conteúdo muda a cada segundo;
  • você precisa de backend robusto;
  • precisa de permissões complexas;
  • precisa de e-commerce dinâmico;
  • a equipe não sabe usar Git nem Markdown;
  • o build estático fica lento demais para seu volume.

Nesses casos, considere WordPress, Ghost, Django, Rails, Laravel, Next.js, Astro, Hugo ou outro stack.

43. Jekyll versus outras ferramentas

FerramentaMelhor paraObservação
JekyllBlogs, docs, GitHub Pages, MarkdownClássico, maduro, Ruby
HugoSites estáticos enormes e builds rápidosFeito em Go, muito veloz
EleventySites estáticos flexíveis em JavaScriptMuito bom para templates variados
AstroSites modernos com componentesMelhor para frontend moderno
Next.jsApps React e sites híbridosMais pesado e dinâmico
WordPressCMS com painel e pluginsMais dinâmico, mais manutenção

Minha opinião direta: para documentação, blog e sites editoriais simples, Jekyll ainda é muito bom. Para frontend moderno com componentes, talvez Astro seja mais agradável. Para site gigante com milhares de páginas, Hugo pode ser mais eficiente.

44. Projeto exemplo: biblioteca digital

Estrutura:

biblioteca/
├── _config.yml
├── _layouts/
│   ├── default.html
│   └── livro.html
├── _livros/
│   ├── kybalion.md
│   └── corpus-hermeticum.md
├── _data/
│   └── autores.yml
├── assets/
└── index.md

_config.yml:

title: Biblioteca Digital
collections:
  livros:
    output: true
    permalink: /livros/:name/

_layouts/livro.html:

---
layout: default
---

<article>
  <h1>{{ page.title }}</h1>
  <p><strong>Autor:</strong> {{ page.autor }}</p>
  <p><strong>Ano:</strong> {{ page.ano }}</p>

  {{ content }}
</article>

_livros/kybalion.md:

---
layout: livro
title: "O Kybalion"
autor: "Três Iniciados"
ano: 1908
---

Descrição, notas e links relacionados.

index.md:

---
layout: default
title: Início
---

# Livros

{% for livro in site.livros %}
- [{{ livro.title }}]({{ livro.url }}) — {{ livro.autor }}
{% endfor %}

Esse projeto vira um catálogo estático completo.

45. Conclusão

Jekyll é uma ferramenta simples, madura e muito útil para quem quer publicar conteúdo sem carregar um CMS inteiro nas costas.

Ele brilha quando você quer:

  • escrever em Markdown;
  • versionar com Git;
  • gerar HTML estático;
  • hospedar barato;
  • ter controle total sobre templates;
  • criar blogs, docs, bibliotecas, zines e catálogos.

Ele falha quando você tenta transformá-lo em algo que ele não é: um CMS dinâmico com painel, login, banco, comentários e lógica de backend.

A combinação prática para servidor é:

Jekyll para gerar
Git para versionar
Jenkins/GitHub Actions para automatizar
Caddy/Nginx para hospedar

Se você quer um site leve, editorial, versionado e fácil de migrar, Jekyll continua sendo uma escolha muito boa. Só não force a ferramenta além do papel dela.

46. Fontes consultadas

Did this resonate?

Related documents