Como garantir que o inferno seja uma amostra grátis do seu trabalho!

• Programação Orientada a Gambiarra - O Livro
  • 📜 Índice
  • 🔖 Descrição do Livro
  • 🔗 Acesso ao Livro
  • 🚧 Status do Livro
  • ⚙️ Como o Projeto Foi Feito
    • Arquitetura Geral
    • Pipeline de Publicação
  • 🔧 Tecnologias Utilizadas
  • 📁 Estrutura do Projeto
  • 💻 Pré-requisitos
  • 🚀 Como Rodar o Projeto
    • 1. Clonar o Repositório
    • 2. Instalar as Dependências
    • 3. Configurar as Variáveis de Ambiente
    • 4. Iniciar o Servidor de Desenvolvimento
    • 5. Gerar o Build de Produção
  • 📝 Como Funciona o Conteúdo
    • Estrutura dos Capítulos
    • Estrutura dos Posts do Blog
    • Status dos Capítulos
    • Ícones
  • 📖 Geração de eBooks
    • Com Pandoc Instalado Localmente
    • Com Docker (Recomendado)
  • 🤖 CI/CD e Automação
  • 🔍 Busca
  • 📱 PWA e Suporte Offline
  • 👦 Autor
  • 💸 Colabore
  • 📄 Licença

O Livro POG é um projeto de documentação da técnica de desenvolvimento de software mais utilizada do mercado, a Programação Orientada a Gambiarra (POG).

O intuito desse livro é documentar a história da POG, fazer uma breve introdução ao assunto, demonstrar quais são os requisitos necessários para o nascimento da POG, explicar as técnicas utilizadas no sumonamento da POG e os principais padrões de projeto de gambiarra: os Gambi Design Patterns (GDPs).

Topo

O livro pode ser acessado gratuitamente em https://livropog.com.br. Versões do livro em EPUB e PDF são geradas automaticamente e podem ser baixadas na página do livro.

Topo

O livro está em desenvolvimento e o status de cada capítulo pode ser verificado em https://livropog.com.br/capitulos. Cada capítulo pode ter um dos seguintes status:

Topo

Este projeto não é apenas um livro — é uma plataforma editorial completa para um livro vivo. A ideia central é ter um ciclo simples e confiável: escrever → versionar → publicar → evoluir.

O conteúdo do livro é escrito em Markdown, versionado no Git e processado pelo Contentlayer, que transforma os arquivos .md em JSON tipado, consumido pela aplicação Next.js.

content/ (Markdown)
    └─► Contentlayer (compila e tipifica)
            └─► Next.js (rotas, componentes, API)
                    └─► Vercel (deploy automático)

Isso mantém uma separação clara entre conteúdo e aplicação: o autor pode focar em escrever sem precisar mexer em código, e o desenvolvedor pode evoluir a plataforma sem quebrar o conteúdo.

Quando um capítulo com status: done é commitado na branch main:

1. O GitHub Actions detecta a mudança nos arquivos de content/capitulos/.
2. O script generate-ebook.js combina os capítulos em um único Markdown.
3. O Pandoc converte esse Markdown para PDF (via XeLaTeX) e EPUB.
4. Os arquivos gerados são commitados de volta no repositório em public/downloads/.
5. A Vercel detecta o novo commit e faz o deploy do site atualizado automaticamente.

Topo

Topo

livro-pog/
├── content/                    # Conteúdo do livro e do blog (Markdown)
│   ├── blog/                   # Posts do blog
│   └── capitulos/              # Capítulos do livro
│       ├── historia.md
│       ├── requisitos/         # Capítulo pai: Requisitos da POG
│       ├── tecnicas/           # Capítulo pai: Técnicas
│       └── gambi-design-patterns/ # Capítulo pai: Gambi Design Patterns
│
├── src/
│   ├── app/                    # Rotas (Next.js App Router)
│   │   ├── (site)/             # Páginas públicas (home, blog, capítulos, busca)
│   │   ├── api/                # API Routes (busca, OG images)
│   │   └── offline/            # Página de fallback offline
│   ├── components/             # Componentes React reutilizáveis
│   ├── config/                 # Configuração de SEO
│   ├── contexts/               # Contextos React (ConfigContext)
│   ├── data/                   # Camada de acesso a dados (Chapters, Posts)
│   ├── lib/                    # Utilitários (OG image, ícones, analytics)
│   ├── styles/                 # Tema MUI, paletas, CSS global
│   └── utils/                  # Funções utilitárias (data, arquivos)
│
├── public/
│   ├── downloads/              # eBooks gerados (PDF, EPUB)
│   ├── images/                 # Imagens estáticas e OG images geradas
│   ├── icons/                  # Ícones do PWA
│   └── manifest.json           # Manifesto do PWA
│
├── scripts/                    # Scripts de build e geração
│   ├── generate-ebook.js       # Combina capítulos em um único Markdown
│   ├── generate-og-images.js   # Pré-gera imagens OpenGraph
│   ├── docker-build.sh         # Constrói imagem Docker para os eBooks
│   ├── docker-generate.sh      # Gera eBooks via Docker
│   └── pandoc/                 # Configurações do Pandoc (PDF e EPUB)
│
├── _bibliography/
│   └── library.bib             # Referências bibliográficas (BibTeX)
│
├── .github/
│   └── workflows/
│       └── generate-ebook.yml  # Pipeline de geração automática dos eBooks
│
├── contentlayer.config.js      # Schema e configuração do Contentlayer
├── next.config.js              # Configuração do Next.js (PWA, aliases, imagens)
├── next-sitemap.config.js      # Configuração do sitemap
├── estrutura-livro.txt         # Ordem de compilação dos capítulos para o eBook
└── EBOOK-DEV.md                # Guia de desenvolvimento dos eBooks

Topo

Antes de começar, você vai precisar de:

• Node.js >= 18 — nodejs.org
• Yarn >= 1.22 — instalável com npm install -g yarn
• Git

Para gerar os eBooks localmente (opcional), você também precisará de:

• Pandoc >= 3.x — pandoc.org
• XeLaTeX (para PDF) — incluso no texlive-full ou MacTeX

Ou simplesmente use o Docker, que já inclui tudo (ver seção Geração de eBooks).

Topo

git clone https://github.com/josenaldo/livro-pog.git
cd livro-pog

yarn install

O projeto já vem com os arquivos .env.development e .env.production. Para desenvolvimento local, nenhuma configuração adicional é necessária. As variáveis disponíveis são:

yarn dev

O site estará disponível em http://localhost:6500.

O Contentlayer processa os arquivos Markdown automaticamente — ao editar qualquer arquivo em content/, o site é recarregado com o conteúdo atualizado.

yarn build

Este comando executa três etapas em sequência:

1. Contentlayer compila os arquivos Markdown em JSON.
2. Next.js gera o build otimizado.
3. next-sitemap gera o sitemap.xml e o robots.txt.

Para rodar o build de produção localmente:

yarn start

Topo

Todo o conteúdo do livro e do blog fica na pasta content/ como arquivos Markdown com frontmatter YAML. O Contentlayer lê esses arquivos, valida os campos e os disponibiliza como dados tipados para a aplicação.

Cada arquivo em content/capitulos/ é um capítulo. Capítulos podem ser organizados em subpastas para criar uma hierarquia (capítulo pai > capítulos filhos).

Exemplo de frontmatter de capítulo:

---
title: "História da POG"
description: "A origem e a evolução da Programação Orientada a Gambiarra"
date: "2024-01-15"
sentence: "Toda grande gambiarra começa com um prazo impossível."
sentence_author: "Sábio Anônimo do Stack Overflow"
name: "historia"
order_number: 1
status: "done"
icon: "tabler/IconBooks"
---

Conteúdo do capítulo em Markdown aqui...

Campos obrigatórios:

Campos opcionais:

Cada arquivo em content/blog/ é um post.

Exemplo de frontmatter de post:

---
title: "Por que todo código vira POG"
description: "Uma análise profunda da inevitabilidade da gambiarra"
date: "2024-03-10"
author: "Josenaldo Matos"
icon: "tabler/IconBug"
---

Conteúdo do post em Markdown...

Apenas capítulos com status: done são incluídos na compilação dos eBooks. Os demais aparecem no site com indicadores visuais de progresso.

Os ícones são referenciados no frontmatter no formato tabler/IconNome, onde IconNome é o nome do componente na biblioteca Tabler Icons. Por exemplo: tabler/IconBooks, tabler/IconBug, tabler/IconCode.

Topo

O projeto gera automaticamente versões em PDF e EPUB do livro usando o Pandoc. Apenas capítulos com status: done são incluídos, e a ordem de compilação é definida pelo arquivo estrutura-livro.txt.

# Gerar apenas o Markdown combinado
yarn ebook:markdown

# Gerar o PDF (requer Pandoc + XeLaTeX)
yarn ebook:pdf

# Gerar o EPUB (requer Pandoc)
yarn ebook:epub

# Gerar todos os formatos
yarn ebook:all

Se você não quiser instalar Pandoc e LaTeX localmente, use o Docker:

# Construir a imagem Docker (apenas uma vez)
yarn ebook:docker:build

# Gerar o PDF via Docker
yarn ebook:docker:pdf

# Gerar o EPUB via Docker
yarn ebook:docker:epub

# Gerar todos os formatos via Docker
yarn ebook:docker:all

Os arquivos gerados ficam em public/downloads/:

• livro-pog.pdf
• livro-pog.epub
• livro-pog-combined.md (Markdown combinado intermediário)

Consulte o arquivo EBOOK-DEV.md para detalhes sobre a configuração do Pandoc e personalização do layout dos eBooks.

Topo

O projeto usa GitHub Actions para gerar os eBooks automaticamente sempre que há mudanças na pasta content/capitulos/ na branch main.

O pipeline (.github/workflows/generate-ebook.yml):

1. Instala Node.js, Pandoc e o ambiente LaTeX completo.
2. Executa generate-ebook.js para combinar os capítulos.
3. Gera o PDF com XeLaTeX (tipografia em português, fonte DejaVu).
4. Gera o EPUB com capa e CSS customizado.
5. Commita os arquivos gerados de volta no repositório com [skip ci].

O deploy na Vercel é acionado automaticamente pelo commit gerado pelo CI, mantendo os downloads sempre atualizados no site de produção.

Topo

A busca é implementada com Lunr.js — uma biblioteca de busca full-text que roda inteiramente no servidor, sem dependência de serviços externos.

Como funciona:

1. A API em /api/search?q={termo} recebe a query.
2. O servidor indexa todos os capítulos e posts (título, descrição e conteúdo).
3. O Lunr executa a busca no índice e retorna os resultados ordenados por relevância.
4. O cliente consome essa API via Axios e exibe os resultados na página de busca (/pesquisa).

Topo

O site é uma Progressive Web App (PWA), o que significa que pode ser instalado no celular ou desktop e funciona mesmo sem conexão com a internet.

Estratégia de cache (Workbox):

• Capítulos já visitados ficam em cache por 7 dias (estratégia NetworkFirst).
• Se o usuário estiver offline e tentar acessar uma página não cacheada, é exibida a página /offline.
• As imagens OpenGraph (/api/og) nunca são cacheadas (sempre buscadas da rede).

Para testar o PWA localmente, defina NEXT_PUBLIC_PWA_DEV=true no arquivo .env.development.

Topo

Olá. Meu nome é Josenaldo de Oliveira Matos Filho. Sou POGramador desde 1999. Durante a maior parte de minha vida profissional (2003-2016), escrevi gambiarras em Java, principalmente Spring e Java EE. Também já me meti a besta com PHP, Ruby, VBA, Flex... E coisas das quais eu me envergonho profundamenrte, como WebSphere e Vignette.

Nasci em Ubatã, uma cidade perdida no interior da Bahia. Moro, desde 2008, em Uberlândia-MG, pra onde fugi depois que abandonei a faculdade pra ganhar dinheiros. Nesse mesmo ano, eu perdi meus dois rins (só não me lembro onde) e passei a fazer hemodiálise.

Hoje, escrevo pogs em Java, Javasrcript, Typescript e Python. Também brinco com Go. mas, no trabalho, o que eu faço é cuidar sozinho de aplicações, entregando de ponta a ponta o seu projeto.

Dentre algumas de minhas mais notáveis realizações fora da TI, estão:

• Criei a Farofa Lampião e Julieta, meu grande legado para a humanidade.
• Quebrei as duas pernas, em momentos diferentes (agosto de 2020 e janeiro de 2022), sendo que a última foi uma FRATURA EXPONTÂNEA.
• Quebrei as duas pernas DE NOVO, em 2025. E dessa vez, fora as duas juntas, numa apoteótica fratura espontânea bilateral de fêmur, o que já me rendeu, até o momento dessa última alteração, mais de 8 meses e cama.
• Perdi o rim da minha sogra.

Quer me achar?

• Website: https://josenaldo.com.br
• Github: @josenaldo
• LinkedIn: @josenaldo
• Bluesky: @josenaldomatos

Topo

Esse é um projeto pessoal de mim mesmo feito somente por minha pessoa. Porém, se algum desenhista quiser utilizar esse projeto para promover, GRATUITAMENTE, a sua arte, ilustrando o monte de porcaria que eu escrevinhei, eu ficaria muito feliz.

Se você quiser colaborar com o projeto, você pode acessar a página Ajude este Projeto e ver como você pode fazer para colaborar financeiramente, sem nenhum compromisso (principalmente de minha parte).

Topo

Copyright © 2021 Josenaldo de Oliveira Matos Filho

Topo