Arquitetura do Sistema

Este documento descreve a arquitetura técnica do site estático construído com Jekyll, incluindo estrutura de diretórios, fluxo de build, hierarquia de componentes e decisões técnicas principais.

Visão Geral do Sistema

Tipo de Projeto

Site estático gerado com Jekyll hospedado no GitHub Pages. O Jekyll processa templates Liquid, Markdown e SCSS para gerar HTML/CSS/JS estáticos que são servidos sem necessidade de servidor backend.

Tecnologias Principais

Filosofia Arquitetural

  1. Separação de Concerns: Código (src/) separado de conteúdo (content/)
  2. Modularidade: Componentes pequenos e reutilizáveis
  3. Progressive Enhancement: Funcionalidades básicas sem JavaScript
  4. Mobile-First: Design responsivo começando pelo mobile
  5. Acessibilidade: WCAG 2.1 AA como objetivo

Estrutura de Diretórios

Organização Principal

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

site-attempt/
├── src/                      # Todo código-fonte Jekyll
│   ├── _layouts/            # Templates de página
│   ├── _includes/           # Componentes reutilizáveis
│   ├── _sass/              # Estilos SCSS modulares
│   ├── _data/              # Arquivos de dados YAML
│   └── assets/             # CSS, imagens, JSON
├── content/                 # Todo o conteúdo do site
│   ├── gatilhos/           # Documentação de aprendizado
│   ├── posts/              # Artigos e posts
│   └── projects/           # Projetos documentados
├── docs/                    # Documentação técnica
├── .github/                 # Workflows e templates
├── _config.yml             # Configuração Jekyll
├── Gemfile                 # Dependências Ruby
└── assets -> src/assets    # Symlink para build

Decisões de Organização

Por que src/ e content/?

Por que symlink para assets/? Jekyll espera assets na raiz. O symlink mantém organização em src/assets/ enquanto Jekyll encontra em assets/.

Fluxo de Build Jekyll

1
2
3
4
5
6
7

1. _config.yml → Configuração (diretórios customizados)
2. content/** → Markdown processado → HTML
3. Layouts aplicados (default → post → gatilho)
4. SCSS compilado (src/_sass → _site/assets/css)
5. Assets copiados (imagens, JSON)
6. Plugins executados (feed, sitemap, SEO)
7. _site/ → Site estático final

Configuração de URLs

Arquivos em content/posts/ são servidos como /posts/ (sem “content/”):

1
2
3
4
5
6

# _config.yml
defaults:
  - scope:
      path: "content/posts"
    values:
      permalink: /posts/:title/

Hierarquia de Layouts

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

default.html (base)
├─> Estrutura HTML, inclui header/footer
├─> Define grid e containers
└─> Fornece 

  post.html (herda default)
  ├─> Adiciona metadata (título, data)
  └─> Formata artigos

    gatilho.html (herda post)
    ├─> Badges específicos
    └─> Navegação contextual

  diario.html (herda default)
  └─> Layout timeline

  pasta.html (herda default)
  └─> Lista subpáginas automaticamente

Componentes Principais

Includes Essenciais

default/head-default.html - Meta tags, CSS, favicons
topbar.html - Controles (tema, fonte), breadcrumb
nav.html - Menu principal
sidebar.html - Navegação contextual, busca
scripts/theme-switcher.html - Toggle claro/escuro
scripts/breadcrumb.html - Geração dinâmica de breadcrumbs

Sistema de Dados

src/_data/repositories.yml - Configuração de projetos externos
src/_data/breadcrumb_config.yml - Configuração de navegação

Arquitetura SCSS

Estrutura Modular

1
2
3
4
5

// assets/css/style.scss
@import "variables";  // Variáveis (cores, espaçamentos)
@import "mixins";     // Mixins reutilizáveis
@import "base";       // Estilos base (html, body)
@import "components"; // Importa todos componentes

Sistema de Temas

Usa CSS variables para permitir toggle dinâmico:

1
2
3
4
5
6
7
8
9

:root {
  --bg-primary: #ffffff;
  --text-primary: #1a1a1a;
}

[data-theme="dark"] {
  --bg-primary: #1a1a1a;
  --text-primary: #f0f0f0;
}

JavaScript altera [data-theme] e localStorage persiste escolha.

Responsividade

Mobile-first com mixins para breakpoints:

1
2
3
4
5
6
7
8

@mixin tablet {
  @media (min-width: 768px) { @content; }
}

.sidebar {
  display: none;
  @include tablet { display: block; }
}

Decisões Técnicas

1. Por que Jekyll?

Prós: GitHub Pages nativo, maduro, sem banco de dados
Contras: Build time cresce, menos poderoso que frameworks modernos
Escolha: Ideal para projeto de aprendizado e documentação estática

2. Estrutura src/ + content/

Facilita manutenção e permite contribuições de conteúdo sem mexer em código.

3. Permalinks sem “content/”

URLs limpas (/posts/ não /content/posts/) são melhores para SEO e UX.

4. Busca Client-Side

JSON local + JavaScript é simples e não requer serviços externos.

5. Tema com CSS Variables

Permite toggle dinâmico sem rebuild, melhor UX que SCSS puro.

Fluxo de Dados

1
2
3
4
5
6
7
8
9

Markdown (content/*) + Front Matter
  ↓
Jekyll processa com Kramdown
  ↓
Aplica layout definido
  ↓
Acessa dados (site.data.*, page.*, site.*)
  ↓
Gera HTML final em _site/

Busca usa JSON gerado em build:

1

Loop site.pages → Extrai title/url/content → JSON → JavaScript

Performance

Otimizações

Métricas Alvo

Segurança

Extensibilidade

Adicionar Layout

  1. Criar src/_layouts/novo.html
  2. Estilos em src/_sass/layouts/_novo.scss
  3. Documentar em guides/

Adicionar Seção

  1. Criar content/nova-secao/
  2. Configurar defaults em _config.yml
  3. Atualizar navegação

Adicionar Componente

  1. Criar src/_includes/componente.html
  2. Estilos em src/_sass/components/_componente.scss
  3. Importar em _components.scss

Limitações

  1. Build time cresce com páginas
  2. Busca só em português
  3. Apenas 2 temas (claro/escuro)
  4. Sem i18n
  5. Sem comentários (estático)

Roadmap

Última atualização: Fevereiro de 2026