Contribuindo com Exemplos de Mecanismos

As páginas de exemplos de mecanismos são as que mais se beneficiam de contribuições da comunidade. Você pode catalogar exemplos de outras equipes ou, idealmente, documentar os mecanismos da sua própria equipe analisando a fundo o projeto (Behind the Design) e seu desempenho real em competição. Se estiver adicionando um mecanismo de outra equipe, tente entrevistá-los para obter informações autênticas e precisas.

Critérios para Exemplos de Mecanismos:

• O mecanismo deve ter sido efetivamente construído e utilizado em uma competição oficial de FRC
• Apresente tanto os pontos fortes quanto os pontos fracos. Para que ele foi projetado? Por que certas escolhas de engenharia foram feitas? Qual foi a facilidade de fabricação e montagem? Como foi o desempenho em campo? O que funcionou bem e o que seria mudado em uma eventual revisão?
• Detalhe partes específicas: materiais utilizados, peças COTS escolhidas, processos de fabricação, cálculos, etc.
• Imagens detalhadas do CAD e/ou do robô real. De preferência, link público do modelo no Onshape.
• Mídias adicionais (vídeos de partidas, fotos de detalhes) quando aplicável.

Como Adicionar Exemplos

Conforme descrito em Formas de Contribuir, existem dois caminhos:

1. Redigir o conteúdo em uma plataforma separada (como Google Docs) para que um mantenedor faça a publicação no site
2. Fazer um fork do repositório e enviar um Pull Request no GitHub (veja o guia técnico Adicionando uma Página)

Adicionando um Exemplo de Mecanismo

Se você possui apenas uma imagem e o link do CAD, não precisa criar uma página dedicada inteira! É possível adicionar a referência diretamente ao index.mdx da categoria. Uma página completa é justificada quando há conteúdo suficiente para um artigo aprofundado (Behind the Design).

Adicionando ao Índice da Categoria (Avançado)

Para adicionar uma referência em CAD sem criar uma página avulsa, adicione uma entrada à matriz exampleCards no arquivo index.mdx da categoria correspondente. Importe sua miniatura no topo do arquivo e insira o objeto do card:

import myMechImage from './img/sua-imagem.webp';

export const exampleCards = [
  // ...entradas existentes...
  {
    title: "Nome do Mecanismo da Equipe XXXX",
    href: 'https://cad.onshape.com/...',
    image: myMechImage,
    imageAlt: 'Descrição resumida da imagem',
    description: 'Uma ou duas frases resumindo as características do design.',
  },
];

Se exampleCards ainda não existir no índice, exporte a matriz e adicione uma seção ## Referências em CAD contendo <MechanismCardGrid cards={exampleCards} /> logo abaixo da grade de artigos.

Criando uma Página Completa

Crie um novo arquivo .mdx na pasta da categoria correspondente usando este modelo:

---
title: Nome do Mecanismo da Equipe XXXX
description: Breve descrição do mecanismo.
template: splash
---

<ContentFigure src="./img/thumb/imagem-principal.webp" alt="Render CAD do mecanismo" width="80%" />

<LinkButton href="https://cad.onshape.com/...">
  Documento no Onshape
</LinkButton>

## Por Trás do Design (Behind the Design)

Conteúdo explicando as decisões de projeto, compensações (tradeoffs), desempenho em campo e lições aprendidas.

Imagens e Miniaturas

As imagens da página do exemplo devem ficar na pasta img/ ao lado do .mdx. As miniaturas usadas na página inicial de mecanismos ficam em img/thumb/.

Utilize formato .webp comprimido via Squoosh.

Para miniaturas, utilize uma proporção de aspecto de 1:1.545 ou 1.545:1, correspondente à proporção de impressão tabloide do Onshape (paisagem para peças largas, retrato para peças altas).

Dica

Para cortar uma imagem na proporção exata, use um editor de imagens (como GIMP ou Photoshop) para identificar a menor dimensão e ajustar a maior para atingir a proporção correta.

Adicionando uma Nova Categoria de Mecanismos (Opcional)

Se o mecanismo que você deseja adicionar ainda não possui categoria, será necessário criá-la. Isso envolve os arquivos de conteúdo MDX e a atualização de um componente Astro:

Nota

Se você não tiver familiaridade com TypeScript ou componentes Astro, crie os arquivos de texto e avise em seu Pull Request que um mantenedor cuidará da inclusão no componente da landing page.

Arquivos de Conteúdo

1. Crie uma nova pasta sob src/content/docs/mechanism-examples/ com o nome da categoria. Se houver subtipos (como elevadores contínuos e em cascata), crie subpastas.
2. Crie um arquivo index.mdx na pasta:

---
title: Nome da Categoria
description: Descrição da categoria de mecanismos.
template: splash
---

# Nome da Categoria

Descrição da categoria e quais tipos de exemplos estão inclusos.

3. Cadastre a categoria em src/config/sidebarConfig.ts.

Componente da Página Principal (Avançado)

A página principal de Exemplos de Mecanismos é gerenciada por src/components/content/MechanismExamplesLanding.astro. Para que a nova categoria apareça como um card, localize o array categories e adicione a nova entrada:

{
  title: 'Nome da Categoria',
  href: '/mechanism-examples/sua-categoria/',
  imageAlt: 'Descrição da imagem',
  description: 'Uma ou duas frases descrevendo a categoria.',
  links: [
    { label: 'Nome da subcategoria', href: '/mechanism-examples/sua-categoria/subtipo/' },
  ],
},

Destacando um Exemplo como Artigo em Destaque (Avançado)

A página de abertura possui uma seção que destaca exemplos de altíssimo nível técnico. Para incluí-lo, edite o array inDepthExamples em src/components/content/MechanismExamplesLanding.astro:

{
  title: "Nome do Mecanismo da Equipe XXXX",
  href: '/mechanism-examples/sua-categoria/sua-pagina/',
  image: imageByLabel('palavra_chave_do_arquivo_thumb'),
  imageAlt: 'Descrição da imagem',
  category: 'Etiqueta da categoria mostrada no card',
  description: 'Duas ou três frases resumindo por que este exemplo se destaca.',
},

Obrigado por ajudar a enriquecer o acervo técnico da comunidade!