Convenções de Código e Organização

Este documento estabelece os padrões de nomenclatura, organização de arquivos, convenções de código SCSS, front matter e permalinks usados neste projeto.

Nomenclatura de Arquivos e Pastas

Regras Gerais

Pastas: Sempre em minúsculas, com hífens para separar palavras

1
2
3
4

✓ conceitos-fundamentais/
✓ diario-de-aprendizado/
✗ Conceitos_Fundamentais/
✗ diarioAprendizado/

Arquivos Markdown: Minúsculas, hífens, extensão .md

1
2
3
4

✓ template-conceito.md
✓ dia_2025-12-25_.md (exceção: templates de diário)
✗ TemplatConceito.md
✗ template_conceito.markdown

Arquivos HTML: Minúsculas, hífens, extensão .html

1
2
3

✓ head-default.html
✓ sidebar.html
✗ HeadDefault.html

Arquivos SCSS: Prefixo _ para partials, minúsculas, hífens

1
2
3
4

✓ _variables.scss
✓ _sidebar.scss
✗ variables.scss (sem underscore)
✗ _sideBar.scss (camelCase)

Nomenclatura por Tipo

Layouts: Substantivo descritivo

Includes: Função ou componente

Data Files: Plural ou descritivo

Imagens: Descritivo, sem espaços

Organização de Diretórios

Estrutura Padrão

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

src/
├── _layouts/        # Um arquivo por layout
├── _includes/       # Organizado por função
│   ├── default/    # Componentes do layout default
│   ├── scripts/    # Features JavaScript
│   └── *.html      # Componentes globais
├── _sass/
│   ├── _*.scss     # Arquivos base (variables, mixins, base)
│   ├── components/ # Um arquivo por componente
│   ├── layouts/    # Estilos específicos de layouts
│   └── screens/    # Media queries por dispositivo
├── _data/          # Arquivos YAML de configuração
└── assets/
    ├── css/        # Entry points SCSS
    ├── images/     # Todas imagens
    └── json/       # Dados para JavaScript

content/
├── gatilhos/       # Por tipo de conteúdo
│   ├── index.md   # Sempre presente
│   └── */         # Subseções com index.md
├── posts/
└── projects/

Regras de Organização

  1. Um arquivo = uma responsabilidade
    • Cada include faz uma coisa
    • Cada SCSS partial é um componente
  2. Hierarquia clara
    • Máximo 3 níveis de profundidade
    • Subpastas quando > 5 arquivos relacionados
  3. Index files obrigatórios
    • Toda pasta de conteúdo tem index.md
    • Define título e layout da seção
  4. README para complexidade
    • Pastas com > 10 arquivos têm README
    • Explica organização interna

Padrões SCSS

Estrutura de Arquivo

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

// 1. Comentário de cabeçalho
/**
 * Component: Sidebar
 * Estilos para barra lateral de navegação
 */

// 2. Variáveis locais (se necessário)
$sidebar-width: 250px;

// 3. Mixins locais (se necessário)
@mixin sidebar-transition {
  transition: transform 0.3s ease;
}

// 4. Estilos do componente
.sidebar {
  width: $sidebar-width;
  @include sidebar-transition;
  
  // 5. Elementos aninhados (max 3 níveis)
  &__header {
    padding: 1rem;
    
    &--active {
      background: var(--bg-active);
    }
  }
  
  // 6. Estados e modificadores
  &:hover {
    transform: translateX(0);
  }
  
  // 7. Media queries no final
  @include tablet {
    width: 300px;
  }
}

Convenções de Nomenclatura CSS

Usamos BEM modificado (Block Element Modifier):

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

// Block
.component { }

// Element (parte do block)
.component__element { }

// Modifier (variação)
.component--modifier { }
.component__element--modifier { }

// Estados (preferir data attributes)
.component[data-state="active"] { }

Exemplos:

1
2
3
4
5

.sidebar { }                    // Block
.sidebar__nav { }               // Element
.sidebar__nav-item { }          // Sub-element
.sidebar--collapsed { }         // Modifier
.sidebar__nav-item--active { }  // Element modifier

Variáveis

Naming:

1
2
3
4
5
6

// Padrão: $tipo-subtipo-propriedade-variação
$color-theme-primary: #6b46c1;
$color-theme-secondary: #805ad5;
$spacing-base-unit: 0.25rem;
$font-size-heading-large: 2rem;
$z-index-modal: 1000;

Organização:

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

// _variables.scss

// === TEMA ===
// Cores primárias
$theme-primary: #6b46c1;
$theme-secondary: #805ad5;

// Cores de fundo
$light-bg: #ffffff;
$dark-bg: #1a1a1a;

// === TIPOGRAFIA ===
$font-family-base: -apple-system, BlinkMacSystemFont, sans-serif;
$font-size-base: 1rem;
$line-height-base: 1.6;

// === SPACING ===
$spacing-unit: 0.25rem;
$spacing-small: calc($spacing-unit * 2);
$spacing-medium: calc($spacing-unit * 4);

// === LAYOUT ===
$container-max-width: 1200px;
$sidebar-width: 250px;

// === Z-INDEX ===
$z-index-sidebar: 100;
$z-index-topbar: 200;
$z-index-modal: 1000;

Mixins

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

// _mixins.scss

// Responsividade
@mixin phone {
  @media (max-width: 767px) { @content; }
}

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

@mixin desktop {
  @media (min-width: 1024px) { @content; }
}

// Utilitários
@mixin flex-center {
  display: flex;
  justify-content: center;
<a href="/site-attempt/docs/CONVENTIONS/">Link</a>

<!-- Escape HTML quando necessário -->
<p></p>

<!-- Formatação de datas -->


<!-- Capitalize, downcase, upcase -->
Conventions

Configuração de Dados

Arquivo src/_data/navigation.yml controla seções da sidebar:

1
2
3
4
5
6
7
8
9
10

sections:
  - name: "Gatilhos"
    path: "gatilhos"
    max_depth: 2
    sort_by: "title"
  
  - name: "Posts"
    path: "posts"
    max_depth: 1
    sort_by: "date"

Campos obrigatórios:

Campos opcionais:

Comportamento:

Repositories.yml

Arquivo src/_data/repositories.yml para modo repositórios:

1
2
3
4
5
6
7

repositories:
  - id: projeto-id
    name: "Nome do Projeto"
    github_url: https://github.com/user/repo
    local_path: /content/projects/projeto/
    description: "Descrição breve"
    updated: "DD/MM/YYYY"

Checklist de Conformidade

Antes de commitar, verifique:

Última atualização: Fevereiro de 2026