Como Usar Nextra Docs e Deploy no Vercel: Guia Passo a Passo

Se você deseja criar um site de documentação elegante e moderno com facilidade, o Nextra Docs é uma das melhores ferramentas disponíveis. Construído sobre o Next.js, o Nextra permite que você escreva sua documentação em Markdown ou MDX, personalize a aparência e o comportamento, e a implemente sem esforço—especialmente no Vercel. Neste artigo, vamos detalhar como configurar um site Nextra Docs do zero e implementá-lo no Vercel gratuitamente.

O Que É o Nextra Docs? Seu Melhor Amigo na Criação de Documentação

O Nextra docs é um framework baseado em Next.js que torna a criação de sites de documentação uma tarefa fácil. Tudo gira em torno de conteúdo em Markdown (ou MDX) com um Tema de Documentação pré-construído que inclui navegação, busca e sumário prontos para uso. Veja por que o nextra docs é incrível:

• Simplicidade do Markdown: Escreva documentação em Markdown ou MDX para conteúdo rico e interativo.
• Recursos do Tema de Documentação: Barra lateral, barra de busca e layouts responsivos gerados automaticamente.
• Poder do Next.js: Aproveita a velocidade, o app router e a integração com o Vercel do Next.js.
• Customizável: Ajuste temas, adicione componentes React ou construa layouts personalizados.
• Código Aberto: Com mais de 3.8 mil estrelas no GitHub, é impulsionado pela comunidade e gratuito.

Os usuários elogiam o nextra docs por seu “polimento sem configuração” e implementações no Vercel. Pronto para construir seu site? Vamos lá!

Por Que Usar o Nextra Docs com o Vercel?

O Nextra docs é perfeito para desenvolvedores, startups ou projetos de código aberto que precisam de documentação de nível profissional rapidamente. Emparelhá-lo com o Vercel—o território nativo do Next.js—significa:

• Implementação Perfeita: O Vercel detecta automaticamente o nextra docs para implementações com um clique.
• Velocidade Incrível: Geração de site estático e CDN para carregamento instantâneo de páginas.
• Hospedagem Gratuita: O nível gratuito do Vercel suporta a maioria dos projetos com domínios personalizados.
• Escalabilidade: Lida com picos de tráfego sem problemas.

Eu implementei um site de teste no Vercel, e ele estava online em menos de 5 minutos—suave como seda!

Como Configurar o Nextra Docs: Guia Passo a Passo

Vamos criar um site nextra docs do zero usando o app router do Next.js. Siga os passos, e você terá um site local rodando em ~20 minutos!

1. Crie um Novo Projeto Next.js

• Abra seu terminal e crie um aplicativo Next.js:

npx create-next-app my-nextra-docs

• Durante a configuração, selecione Sim para todos os prompts, exceto:
• “Gostaria de customizar o alias de importação (@/* por padrão)?” (escolha Não ou sua preferência).
• “Gostaria que seu código ficasse dentro de um diretório src/?” (escolha Não ou Sim—recomendo escolher Não para simplificar).
• Navegue até a pasta do projeto:

cd my-nextra-docs

2. Instale as Dependências do Nextra Docs

Instale os pacotes principais para o nextra docs:

npm install next react react-dom nextra nextra-theme-docs

3. Atualize os Scripts do package.json

Certifique-se de que o package.json inclua estes scripts (eles geralmente são adicionados pelo create-next-app):

"scripts": {
  "dev": "next",
  "build": "next build",
  "start": "next start"
}

• Para um modo de desenvolvimento mais rápido, você pode adicionar o Turbopack (opcional):

"dev": "next --turbopack"

• Teste a configuração:

npm run dev

Visite http://localhost:3000 para confirmar que o aplicativo Next.js funciona.

Feio:( Mas funciona! Agora vamos tentar consertar isso.

4. Configure o Nextra Docs

• Renomeie next.config.ts para next.config.mjs e substitua seu conteúdo por:

import nextra from 'nextra'

const withNextra = nextra({
  theme: 'nextra-theme-docs',
  themeConfig: './theme.config.js'
})

export default withNextra({
  async redirects() {
    return [
      {
        source: '/',
        destination: '/resources',
        permanent: true
      }
    ]
  }
})

• Se você receber um erro no tsconfig.json, seu IDE (por exemplo, VS Code) pode sugerir corrigi-lo automaticamente. Caso contrário, abra o tsconfig.json e adicione "next.config.mjs" ao array include:

"include": ["next-env.d.ts", "**/*.ts", "**/*.tsx", "next.config.mjs", ".next/types/**/*.ts"]

5. Configure os Componentes MDX

• Crie o arquivo mdx-components.js na raiz do projeto:

import { useMDXComponents as getThemeComponents } from 'nextra-theme-docs'

const themeComponents = getThemeComponents()

export function useMDXComponents(components) {
  return {
    ...themeComponents,
    ...components
  }
}

6. Atualize o Layout do Aplicativo

• Substitua o conteúdo de app/layout.tsx (ou src/app/layout.tsx se você escolheu src/):

import { Footer, Layout, Navbar } from 'nextra-theme-docs'
import { Banner, Head } from 'nextra/components'
import { getPageMap } from 'nextra/page-map'
import 'nextra-theme-docs/style.css'
 
export const metadata = {
  // Define your metadata here
  // For more information on metadata API, see: https://nextjs.org/docs/app/building-your-application/optimizing/metadata
}
 
const banner = <Banner storageKey="some-key">Nextra 4.0 is released 🎉</Banner>
const navbar = (
  <Navbar
    logo={<b>Nextra</b>}
    // ... Your additional navbar options
  />
)
const footer = <Footer>MIT {new Date().getFullYear()} © Nextra.</Footer>
 
export default async function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html
      // Not required, but good for SEO
      lang="en"
      // Required to be set
      dir="ltr"
      // Suggested by `next-themes` package https://github.com/pacocoursey/next-themes#with-app
      suppressHydrationWarning
    >
      <Head
      // ... Your additional head options
      >
        {/* Your additional tags should be passed as `children` of `<Head>` element */}
      </Head>
      <body>
        <Layout
          banner={banner}
          navbar={navbar}
          pageMap={await getPageMap()}
          docsRepositoryBase="https://github.com/shuding/nextra/tree/main/docs"
          footer={footer}
          // ... Your additional layout options
        >
          {children}
        </Layout>
      </body>
    </html>
  )
}

7. Adicione Páginas de Documentação

• Exclua app/page.tsx (ou src/app/page.tsx). Isso fará com que nosso aplicativo gere um erro 404 na página inicial. Não se preocupe, nós resolvemos isso!

• Crie uma pasta resources em app (ou src/app):

/app/resources
  /page.mdx

• Adicione conteúdo de exemplo ao app/resources/page.mdx:

Para fins de teste, adicionei:

# Resources

Resources related to various topics and fields.

## Learning
- [Build Your Own X](https://github.com/codecrafters-io/build-your-own-x): Master programming by recreating your favourite technologies from scratch.

## Useful Articles
- [CSR vs SSR vs SSG vs ISR: A Deep Dive for Modern Web Development](csr-vs-ssr-vs-ssg-vs-isr-a-deep-dive-for-modern-web-development-33kl#:~:text=Here's%20a%20quick%20summary%3A,as%20SPAs%2C%20CSR%20is%20perfect.)
- [The Art of Comand Line](https://github.co./jlevy/the-art-of-command-line)

Mas o conteúdo não precisa ser complexo e pode ser tão simples quanto:

# Getting Started

Hi <Your Name>! Welcome to your **nextra docs** site:)

- Easy Markdown editing
- Automatic navigation
- Search and TOC built-in

• O redirecionamento em next.config.mjs corrige o erro 404 redirecionando / para /resources. Simplesmente atualize http://localhost:3000 para ver a página inicial do seu nextra docs—que legal!

Vá em frente - edite esta página, adicione mais páginas e experimente todos os recursos, como modo claro/escuro. O poder está em suas mãos, e as opções são infinitas!

Implementando o Nextra Docs no Vercel

Agora, vamos colocar seu site nextra docs online no Vercel—super fácil, já que o Vercel foi construído para o Next.js.

8. Envie Seu Código para o GitHub

• Inicialize um repositório Git:

git init
git add .
git commit -m "Initial nextra docs"
git remote add origin https://github.com/yourusername/your-repo.git
git push -u origin main

• Crie um novo repositório no GitHub primeiro, substituindo yourusername/your-repo pelos seus detalhes.

9. Implemente no Vercel

• Vá para vercel.com, cadastre-se ou faça login.

• Clique em New Project e importe seu repositório GitHub.
• O Vercel detecta automaticamente seu projeto nextra docs (as configurações do Next.js se aplicam).
• Clique em Deploy. Em ~3 minutos, seu site estará online em uma URL como https://my-nextra-docs.vercel.app.
• Eu implementei o meu, e a configuração do domínio personalizado foi muito fácil!

Customizando Seu Site Nextra Docs

Quer deixar seu nextra docs mais atraente? Experimente estas opções:

• Adicione Páginas: Coloque mais arquivos .mdx em /app ou subpastas como /resources.
• Ajustes de Tema: Atualize theme.config.js para cores, fontes ou opções de barra lateral (veja nextra.site/docs).
• Componentes Personalizados: Estenda mdx-components.js ou crie uma pasta /components.
• Configuração de Busca: Habilite a busca Algolia via theme.config.js para busca de texto completo.
• Código Interativo: Adicione Sandpack ou react-live para playgrounds de código interativos.

Adicionei um componente de callout personalizado à minha documentação—pareceu profissional em 10 minutos!

Solução de Problemas e Dicas para o Nextra Docs

• Erro 404 persiste? Certifique-se de que o redirecionamento em next.config.mjs aponte para /resources.
• Erros de TS? Verifique se o tsconfig.json inclui next.config.mjs.
• Implementação no Vercel falha? Verifique os scripts do package.json e limpe o cache do Vercel.
• Confusão com o app router? O Nextra docs 4+ usa o app router do Next.js; versões mais antigas suportam o pages router.
• Quer exemplos? Clone o repositório do Nextra ou verifique nextra.site.
• Dica de velocidade: Use Turbopack (next --turbopack) para desenvolvimento local mais rápido.

Por Que Nextra Docs e Vercel São um Par Perfeito

O Nextra docs torna a documentação divertida com sua simplicidade Markdown e a velocidade do Next.js. As implementações com um clique do Vercel e a hospedagem gratuita fecham o negócio. Claro, o app router pode confundir os novatos no Next.js, mas a documentação do Nextra é sólida. Comparado ao Docusaurus, o nextra docs parece mais leve e moderno.

Pronto para lançar sua documentação? Construa seu site nextra docs e implemente no Vercel—estou ansioso para ver sua criação! E definitivamente confira o Apidog.