refactor: Atualizar documentação e estrutura de arquivos para melhor organização e clareza

Author: felurye

.github/CONTRIBUTING.md

@@ -1,69 +1,106 @@
-# Guia de Contribuição
+# Guia de Contribuicao
 
-Obrigado por querer contribuir com o Java Labs!
+Obrigado por querer contribuir com o Java Labs.
 
 ## O que pode ser contribuido
 
-- Melhorias e correções nos conteúdos (`/notes`)
-- Novos exemplos de código em `/examples`
-- Exercícios adicionais em `/exercicios`
-- Projetos práticos em `/projetos`
-- Recursos recomendados em `/recursos`
+- Melhorias e correcoes nas notas em `src/content/docs/`
+- Novos exemplos de codigo em `examples/`
+- Exercicios adicionais em `examples/exercises.md`
+- Projetos praticos em `examples/projects.md`
+- Recursos recomendados em `src/content/docs/recursos.md`
+- Melhorias no site Astro + Starlight
 
 ## Processo
 
-1. Crie uma branch a partir de `main` seguindo o padrão:
-   ```
+1. Crie uma branch a partir de `main` seguindo o padrao:
+
+   ```text
    feature/descricao-curta
    fix/descricao-curta
    docs/descricao-curta
    ```
 
-2. Faça commits atômicos com mensagens no padrão de Conventional Commits:
-   ```
-   feat: adicionar exercícios sobre loops
-   fix: corrigir exemplo de recursão
-   docs: melhorar conteúdo sobre herança
+2. Faca commits atomicos com mensagens no padrao Conventional Commits:
+
+   ```text
+   feat: adicionar exercicios sobre loops
+   fix: corrigir exemplo de recursao
+   docs: melhorar conteudo sobre heranca
    ```
 
-   Tipos válidos: `feat`, `fix`, `docs`, `style`, `refactor`, `chore`
+   Tipos validos: `feat`, `fix`, `docs`, `style`, `refactor`, `chore`
+
+3. Abra um Pull Request usando o template do repositorio.
+
+4. Apos aprovacao, o merge sera feito por uma pessoa mantenedora.
+
+## Rodando o site localmente
+
+O Java Labs usa Astro + Starlight para publicar a documentacao.
+
+```bash
+npm install
+npm run dev
+```
+
+O site fica disponivel em `http://localhost:4321`.
+
+Para validar antes de abrir o PR:
+
+```bash
+npm run build
+npm run preview
+```
+
+## Padroes de conteudo
 
-3. Abra um Pull Request usando o template disponível e aguarde revisão.
+### Notas em `src/content/docs/`
 
-4. Após aprovação, o merge será feito por um mantenedor.
+- Escreva em portugues (pt-BR)
+- Use titulos hierarquicos (`##`, `###`)
+- Prefira exemplos curtos e objetivos
+- Explique o "por que" alem do "como"
+- Nomeie arquivos com prefixo numerico quando fizer parte da trilha, por exemplo `04-variaveis.md`
+- Use frontmatter Starlight completo
 
-## Padrões de conteúdo
+Frontmatter recomendado:
 
-### Documentação (Markdown)
+```yaml
+---
+title: "Titulo da nota"
+description: "Resumo curto explicando o foco da pagina."
+lastUpdated: 2026-01-01
+sidebar:
+  order: 4
+tags: ["java", "tema", "iniciante"]
+---
+```
 
-- Escreva em português (pt-BR)
-- Use títulos hierárquicos (`##`, `###`)
-- Prefira exemplos curtos e diretos
-- Inclua o "por quê", não apenas o "como"
-- Nomeie os arquivos com prefixo numérico sequencial: `03-nome-do-topico.md`
-- Atualize o índice em `notes/README.md` ao adicionar um novo tópico
+Se a nota ficar melhor agrupada por assunto, voce pode criar subpastas dentro de `src/content/docs/`.
 
-### Exemplos de código (`/examples`)
+### Exemplos em `examples/`
 
-- Um conceito por pasta, nomeada com prefixo sequencial: `02-NomeDoExemplo/`
-- Inclua um comentário no topo do arquivo explicando o que o exemplo demonstra
-- Adicione um `README.md` na pasta com instruções de execução
-- Teste o código antes de submeter: `javac Arquivo.java && java Arquivo`
+- Um conceito por pasta, nomeada com prefixo sequencial quando fizer sentido, por exemplo `02-Variaveis/`
+- Inclua um comentario no topo do arquivo explicando o objetivo do exemplo
+- Adicione um `README.md` na pasta com contexto e instrucoes de execucao
+- Teste o codigo antes de submeter com `javac Arquivo.java` e `java NomeDaClasse`
 
-### Exercícios (`/exercicios`)
+### Exercicios em `examples/exercises.md`
 
 - Descreva claramente o objetivo
-- Indique o nível de dificuldade (iniciante / intermediário / avançado)
-- Inclua exemplos de saída esperada
-- Use critérios de sucesso em formato de checklist
+- Indique o nivel de dificuldade quando necessario
+- Inclua exemplos de saida esperada
+- Use criterios de sucesso em formato de checklist
+- Aponte para notas relacionadas em `src/content/docs/` quando isso ajudar
 
-### Projetos (`/projetos`)
+### Projetos em `examples/projects.md`
 
 - Descreva o objetivo e o contexto
-- Liste os requisitos em formato de checklist
-- Inclua ao menos um exemplo de uso ou saída esperada
-- Adicione dicas para quem está começando
+- Liste requisitos em formato de checklist
+- Inclua ao menos um exemplo de uso ou saida esperada
+- Adicione dicas para quem esta comecando
 
-## Dúvidas?
+## Duvidas
 
 Abra uma issue com a tag `question`.

.github/PULL_REQUEST_TEMPLATE.md

@@ -4,21 +4,22 @@
 
 ## Tipo de mudança
 
-- [ ] Novo conteúdo (`/docs`)
-- [ ] Novo exemplo de código (`/codigos`)
-- [ ] Novo exercício (`/exercicios`)
-- [ ] Novo projeto (`/projetos`)
-- [ ] Recurso recomendado (`/recursos`)
+- [ ] Nova anotação (`src/content/docs/`)
+- [ ] Novo exemplo (`examples/`)
+- [ ] Novo exercício (`examples/exercises.md`)
+- [ ] Novo projeto (`examples/projects.md`)
 - [ ] Correção de conteúdo existente
+- [ ] Melhoria no site (Astro/Starlight)
 - [ ] Outro: <!-- descreva -->
 
 ## Checklist
 
 - [ ] O conteúdo está em português
 - [ ] Os arquivos estão no diretório correto
+- [ ] As notas usam frontmatter Starlight válido, quando aplicável
 - [ ] Exemplos de código compilam e executam sem erros
 - [ ] Exercícios e projetos têm objetivo e critérios de sucesso descritos
-- [ ] O índice (`notes/README.md`) foi atualizado, se necessário
+- [ ] Links e referências internas foram revisados
 - [ ] Minha branch está atualizada com `main`
 - [ ] Não há conflitos de merge
 

.gitignore

@@ -1,27 +1,42 @@
-# Compiled class files
-*.class
+# Build output
+dist/
 
-# Log files
-*.log
+# Astro
+.astro/
 
-# BlueJ files
-*.ctxt
+# Dependencies
+node_modules/
 
-# Mobile Tools for Java (J2ME)
-.mtj.tmp/
+# Environment
+.env
+.env.*
+!.env.example
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Editor
+.vscode/
+.idea/
+*.swp
+*.swo
 
-# Package Files
+# Java
+*.class
+*.log
+*.ctxt
+.mtj.tmp/
 *.jar
 *.war
 *.nar
 *.ear
 *.zip
 *.tar.gz
 *.rar
-
-# Virtual machine crash logs
 hs_err_pid*
 replay_pid*
+local.properties
 
 # Eclipse
 .classpath
@@ -30,7 +45,6 @@ replay_pid*
 bin/
 
 # IntelliJ IDEA
-.idea/
 *.iml
 *.iws
 *.ipr
@@ -40,12 +54,8 @@ out/
 nbproject/
 build/
 nbbuild/
-dist/
 nbdist/
 .nb-gradle/
-
-# VS Code
-.vscode/
 *.code-workspace
 
 # Maven
@@ -62,58 +72,4 @@ buildNumber.properties
 
 # Gradle
 .gradle/
-build/
 !gradle-wrapper.jar
-
-# macOS
-.DS_Store
-.AppleDouble
-.LSOverride
-
-# Windows
-Thumbs.db
-ehthumbs.db
-Desktop.ini
-$RECYCLE.BIN/
-
-# Linux
-*~
-.directory
-
-# Temporary files
-*.tmp
-*.bak
-*.swp
-*~.nib
-local.properties
-
-# Node (for any web tools)
-node_modules/
-npm-debug.log*
-
-# Jekyll
-_site/
-.sass-cache/
-.jekyll-cache/
-.jekyll-metadata
-
-# Build output
-dist/
-
-# Astro
-.astro/
-
-# Environment
-.env
-.env.*
-!.env.example
-
-# OS
-.DS_Store
-Thumbs.db
-
-# Editor
-.vscode/
-.idea/
-*.swp
-*.swo