Adicionando uma Página

Esta página cobre todo o processo técnico de criação de novas páginas: estrutura de pastas, frontmatter, tratamento de imagens, componentes visuais e registro na barra lateral.

Estrutura de Arquivos

Todo o conteúdo reside na pasta src/content/docs/. Cada seção do site corresponde a uma subpasta:

src/content/docs/
  learning-course/
  design-handbook/
  mechanism-examples/
  best-practices/
  resources/
  contribution/

Nomeie os arquivos em minúsculas separadas por hífens: minha-nova-pagina.mdx. Utilize index.mdx para as páginas de abertura de cada seção.

As imagens de cada página devem ser guardadas em uma pasta img/ ao lado do respectivo arquivo .mdx:

src/content/docs/best-practices/
  assembly-setup.mdx
  img/
    assembly.webp
    originCubeFeature.webp

Frontmatter (Cabeçalho da Página)

Toda página deve iniciar com um bloco de frontmatter YAML. Os campos title e description são obrigatórios:

---
title: Título da Página
description: Resumo de uma ou duas frases para mecanismos de busca e pré-visualizações.
---

Campos opcionais comuns:

tableOfContents: false: oculta o índice da página (útil para páginas de visão geral/índice)
prev: false / next: false: remove os botões de navegação para página anterior/próxima
template: splash: layout de largura total sem barra lateral (usado nas páginas principais de mecanismos e início)

Apenas criar o arquivo .mdx não é suficiente: você também deve cadastrar a nova página em src/config/sidebarConfig.ts, caso contrário ela não aparecerá na barra de navegação.

Localize a seção correspondente à localização do seu arquivo e adicione a entrada:

{ label: 'Título da Sua Página', slug: 'secao/seu-arquivo' }

Por exemplo, para adicionar uma página em src/content/docs/best-practices/fiacao.mdx:

// Na seção '/best-practices':
{ label: 'Boas Práticas de Fiação', slug: 'best-practices/fiacao' }

Para criar um grupo retrátil de páginas, utilize a propriedade collapsed:

{
  label: 'Nome do Grupo',
  collapsed: true,
  items: [
    { label: 'Primeira Página', slug: 'secao/primeira-pagina' },
    { label: 'Segunda Página', slug: 'secao/segunda-pagina' },
  ],
},

Execute npm run dev e confirme se a página aparece corretamente na barra lateral antes de submeter sua contribuição.

Renomeando ou Movendo Páginas

Renomeie ou mova o arquivo .mdx
Atualize o slug correspondente em src/config/sidebarConfig.ts
Pesquise no projeto por links internos que apontavam para o caminho antigo e atualize-os

Evite renomear páginas sem um motivo forte, pois isso quebra links externos, favoritos e indexação de buscas!

Imagens

Comprima todas as imagens para o formato .webp utilizando o Squoosh antes de adicioná-las ao repositório.

Coloque as imagens na pasta img/ adjacente ao arquivo .mdx e referencie-as com caminho relativo:

<ContentFigure src="./img/minha-imagem.webp" alt="Descrição clara da imagem" />

Adicione uma legenda inserindo o texto entre as tags de abertura e fechamento:

<ContentFigure src="./img/minha-imagem.webp" alt="Descrição" width="80%">
  Texto da legenda aqui. Suporta formatação em **markdown** e [links](url).
</ContentFigure>

Vídeos

Hospede vídeos no YouTube e incorpore-os utilizando o ID do vídeo ou a URL completa:

<ContentFigure src="ID_DO_VIDEO" />

<ContentFigure src="https://youtu.be/ID_DO_VIDEO">
  Legenda opcional do vídeo
</ContentFigure>

Componentes Disponíveis

Os componentes ContentFigure, Aside, Slides, LinkButton e ImageTable estão disponíveis globalmente em todos os arquivos .mdx sem necessidade de importação explícita. Outros componentes requerem um import manual no topo da página:

import ContributorList from '@components/content/ContributorList.astro';

ContentFigure

Renderiza imagens, vídeos do YouTube e animações WebP.

<ContentFigure src="./img/exemplo.webp" alt="Texto alternativo" />
<ContentFigure src="./img/exemplo.webp" alt="Texto alternativo" width="60%" border />
<ContentFigure src="ID_DO_VIDEO" width="80%">Legenda</ContentFigure>
<ContentFigure src="./img/animacao.webp" gif />

Utilize align para ajustar o alinhamento horizontal (padrão é center):

<ContentFigure src="./img/exemplo.webp" alt="Texto alternativo" align="left" width="50%" />

Utilize captionPosition para posicionar a legenda ao lado da imagem em vez de abaixo dela:

<ContentFigure src="./img/exemplo.webp" alt="Texto alternativo" width="60%" captionPosition="right">
  A legenda é exibida à direita da imagem.
</ContentFigure>

Aside (Caixas de Destaque)

Caixas estilizadas para dicas, notas, avisos de atenção e exemplos.

<Aside type="tip">Uma dica útil e prática.</Aside>
<Aside type="note">Contexto adicional importante.</Aside>
<Aside type="caution">Atenção a este ponto crítico.</Aside>
<Aside type="danger">Aviso de perigo ou risco grave.</Aside>
<Aside type="example">Um exemplo prático.</Aside>

Adicione um título customizado com a propriedade title. Use collapse para torná-la retrátil:

<Aside type="note" title="Título Personalizado" collapse>
  Conteúdo recolhido por padrão.
</Aside>

Slides (Apresentações Interativas)

Slideshow passo a passo com lightbox ampliado. Cada linha com imagem é um slide; a linha seguinte é sua legenda. Suporta imagens, vídeos do YouTube e arquivos locais.

<Slides>
  ![Texto alternativo](./img/passo1.webp)
  Legenda detalhada do passo 1.

  ![Texto alternativo](./img/passo2.webp)
  Legenda detalhada do passo 2.

  ![](https://www.youtube.com/watch?v=ID_DO_VIDEO)
  Legenda do slide com vídeo.
</Slides>

Links completos do YouTube, links curtos youtu.be/ e IDs de 11 caracteres funcionam perfeitamente. Arquivos locais .webm e .mp4 também são aceitos.

Utilize scale (0 a 1, padrão 0.8) para definir a largura proporcional ocupada pelo slideshow:

<Slides scale={0.6}>
  ![Texto alt](./img/passo1.webp)
  Legenda do passo 1.
</Slides>

ContentRow

Posiciona múltiplos elementos ContentFigure lado a lado em uma mesma linha.

<ContentRow>
  <ContentFigure src="./img/a.webp" alt="A">Legenda A</ContentFigure>
  <ContentFigure src="./img/b.webp" alt="B">Legenda B</ContentFigure>
</ContentRow>

Use mediaHeight para padronizar todas as imagens na mesma altura para que as legendas fiquem alinhadas, e gap para controlar o espaçamento:

<ContentRow mediaHeight="18rem" gap="1rem">
  <ContentFigure src="./img/a.webp" alt="A" />
  <ContentFigure src="./img/b.webp" alt="B" />
  <ContentRowCaption>Legenda compartilhada para ambas as imagens. Suporta **markdown**.</ContentRowCaption>
</ContentRow>

ContentRow requer importação explícita:

import ContentRow from '@components/content/ContentRow.astro';
import ContentRowCaption from '@components/content/ContentRowCaption.astro';

LinkButton

Botão destacado em verde, normalmente usado para links de documentos CAD no Onshape.

<LinkButton href="https://cad.onshape.com/...">Documento no Onshape</LinkButton>
<LinkButton href="https://cad.onshape.com/..." center>Botão Centralizado</LinkButton>

ImageTable

Envolve tabelas em Markdown que contêm imagens na última coluna, garantindo rolagem horizontal em celulares e dimensionamento uniforme das miniaturas.

<ImageTable>
| Tipo | Descrição | Imagem |
|---|---|---|
| **SHCS** | Parafuso sextavado padrão | <ContentFigure src="./img/shcs.webp" alt="SHCS" /> |
| **BHCS** | Parafuso de cabeça abaulada | <ContentFigure src="./img/bhcs.webp" alt="BHCS" /> |
</ImageTable>

Propriedades opcionais para ajuste de dimensões:

<ImageTable minWidth="760px" imageMaxWidth="8rem" imageMaxHeight="6.5rem" imageMinHeight="5rem">

Propriedades:

minWidth: largura mínima antes de ativar a rolagem horizontal, padrão 560px
imageMaxWidth: largura máxima das imagens na coluna final, padrão 7rem
imageMaxHeight: altura máxima das imagens na coluna final, padrão 6rem
imageMinHeight: altura mínima das células de imagem para manter linhas alinhadas, padrão 4rem

Conteúdo Centralizado

Utilize a diretiva :::center para centralizar textos, equações ou legendas:

:::center
**Texto ou fórmula centralizada**
:::

Links e Referências

Links internos: utilize caminhos relativos à raiz: [Texto do Link](/secao/pagina/)
Links externos: abrem em nova aba por padrão com LinkButton; em links markdown tradicionais, abrem na mesma aba a menos que especificado com atributos adicionais.
Modelos Onshape: utilize sempre <LinkButton> para garantir destaque visual.

Sumário / Índice da Página (Table of Contents)

O índice lateral está desativado globalmente por padrão na maioria das páginas. Pode ser ativado em três níveis de prioridade:

Frontmatter da página (maior prioridade):

tableOfContents: false  # força ocultação
tableOfContents: true   # força exibição

Configuração por diretório (src/config/tocConfig.ts): ativa o índice para todas as páginas sob determinada rota. Atualmente habilitado para /design-handbook.
Padrão global (menor prioridade): desativado em todo o site.

O sumário exibe cabeçalhos de nível ## (h2) e ### (h3) por padrão.