Snippets
Blocos de conteúdo reutilizáveis que você pode importar em várias páginas. Armazene textos, componentes ou código comuns no diretório snippets.
Snippets são blocos de conteúdo reutilizáveis armazenados em um diretório /snippets. Importe-os em qualquer página MDX para evitar a duplicação de conteúdo.
Criar trechos
Crie um diretório /snippets na raiz da sua documentação:
my-docs/
├── docs.json
├── introduction.mdx
└── snippets/
├── prerequisites.mdx
├── installation.mdx
└── support-cta.mdx
Escreva o conteúdo do snippet como qualquer arquivo MDX, mas sem frontmatter:
Before you begin, make sure you have:
- Node.js 20 or higher
- A GitHub account
- A text editor (VS Code recommended)Usar trechos
Importe e use snippets nas suas páginas:
---
title: Getting Started
---
## Prerequisites
import Prerequisites from '/snippets/prerequisites.mdx';
<Prerequisites />
## Installation
Continue with your page content...Componentes de trechos
Snippets podem conter componentes do Jamdesk:
<Columns cols={2}>
<Card title="Documentation" icon="book" href="/docs">
Browse our guides
</Card>
<Card title="Contact Support" icon="headset" href="/support">
Get help from our team
</Card>
</Columns>Use em qualquer página:
import SupportCTA from '/snippets/support-cta.mdx';
## Need Help?
<SupportCTA />
Trechos interativos
Use arquivos .tsx com a diretiva 'use client' para snippets que precisam de hooks do React (useState, useEffect, etc.):
'use client';
import { useState } from 'react';
export function Counter() {
const [count, setCount] = useState(0);
return (
<button onClick={() => setCount(c => c + 1)}>
Count: {count}
</button>
);
}Importe no MDX:
import { Counter } from '/snippets/counter';
<Counter />
A diretiva 'use client' é obrigatória para qualquer componente que use hooks do React. Omiti-la causa erros como "useState is not defined".
Trechos parametrizados
Passe props para tornar os snippets dinâmicos:
export const ApiKeyWarning = ({ service }) => (
<Warning>
Never commit your {service} API key to version control. Use environment variables instead.
</Warning>
);Use com props:
import { ApiKeyWarning } from '/snippets/api-key-warning.mdx';
<ApiKeyWarning service="Stripe" />
Organizar trechos
Organize os snippets em subdiretórios em projetos maiores:
snippets/
├── components/
│ ├── cta-cards.mdx
│ └── feature-table.mdx
├── warnings/
│ ├── api-key.mdx
│ └── deprecation.mdx
└── shared/
├── prerequisites.mdx
└── support-links.mdx
Importe com o caminho completo:
import CtaCards from '/snippets/components/cta-cards.mdx';
import ApiKeyWarning from '/snippets/warnings/api-key.mdx';
Casos de uso comuns
| Caso de uso | Exemplo |
|---|---|
| Pré-requisitos | Requisitos do sistema, configuração de conta |
| Etapas de instalação | Comandos de instalação da CLI em diferentes plataformas |
| Autenticação de API | Configuração de autenticação repetida em vários endpoints |
| CTAs de suporte | Links de contato no final de páginas de solução de problemas |
| Avisos de descontinuação | Avisos sobre recursos desatualizados |
| Exemplos de código | Padrões de código reutilizáveis |
Trecho vs. componente inline
| Recurso | Snippet | Componente inline |
|---|---|---|
| Reutilizável entre páginas | Sim | Não (específico da página) |
| Pode usar hooks do React | Sim (com 'use client') | Não |
| Pode importar pacotes externos | Sim (arquivos .tsx) | Não |
| Sintaxe | Instrução de importação | export const no MDX |
Use snippets para conteúdo que aparece em várias páginas. Use componentes inline para componentes de apresentação pontuais em uma única página.
