Especificações do Projeto Webapp

Este documento detalha a estrutura técnica e as características do projeto atual (Webapp).

1. Visão Geral

O projeto é construído sobre o framework Astro (v5.16), focado em performance e entrega de conteúdo estático com hidratação parcial (Islands Architecture).

Stack Tecnológico

  • Framework Core: Astro
  • Linguagem: TypeScript
  • Estilização: SCSS (Sass) com arquitetura de Design Tokens
  • Conteúdo: MDX, Markdown e integração planejada com Typst
  • Matemática: Suporte a LaTeX via remark-math e rehype-katex

2. Estrutura de Diretórios

A organização do código fonte em src/ segue o padrão do Astro:

src/
├── components/   # Componentes reutilizáveis (.astro)
├── content/      # Coleções de dados (MDX/MD)
├── layouts/      # Wrappers de página (Base.astro)
├── pages/        # Roteamento baseado em arquivo
├── scripts/      # Lógica client-side (TypeScript)
├── styles/       # Arquitetura CSS/SCSS
└── utils/        # Funções auxiliares

3. Coleções de Conteúdo (src/content)

O projeto utiliza a Content Layer do Astro 5, definida em src/content.config.ts, com quatro coleções principais:

ColeçãoTipoLoaderSchema
blogPostagensGlobtitle, date, tags, image
eduCursos/PostsGlobtype, course, difficulty
storeProdutosGlobprice, category, featured
papersArtigosGlobauthor, published

Exemplo de definição (Zod):

const edu = defineCollection({
  loader: glob({ pattern: '**/*.{md,mdx}', base: './src/content/edu' }),
  schema: z.object({
    title: z.string(),
    type: z.enum(['course', 'post']),
    course: z.string().optional(),
    difficulty: z.enum(['iniciante', 'intermediario', 'avancado']).optional()
  })
});

4. Estilização e Temas

A estilização utiliza SCSS com uma arquitetura robusta de tokens.

Arquitetura (src/styles/)

  • _tokens.scss: Definições atômicas de design.
  • _theme-maps.scss: Mapeamento semântico.
  • _contrast.scss: Mixins para controle de contraste.

Funcionalidades

  • Dark/Light Mode: Gerenciado via atributos data-theme no <html>.
  • Contraste: Suporte a data-contrast="high" para acessibilidade.
  • Persistência: Script inline no Base.astro restaura preferências do usuário (localStorage).

5. Roteamento e Páginas

O roteamento é híbrido:

  1. Estático: src/pages/index.astro, about/.
  2. Dinâmico: src/pages/blog/[slug].astro, edu/[...slug].astro.

6. Configurações Específicas

O arquivo astro.config.mjs habilita suporte avançado a Markdown:

export default defineConfig({
  integrations: [
    mdx({
      remarkPlugins: [remarkMath],
      rehypePlugins: [rehypeKatex]
    })
  ]
});

Isso permite renderizar equações matemáticas diretamente nos arquivos .mdx:

∮∂ΣE⋅dl=−ddt∬ΣB⋅dS\oint_{\partial \Sigma} \mathbf{E} \cdot d\mathbf{l} = -\frac{d}{dt} \iint_{\Sigma} \mathbf{B} \cdot d\mathbf{S}

Documento gerado automaticamente em 21/01/2026.