---
title: Guia de migração
description: Migrando de outra plataforma de documentação? O Jamdesk pode automatizar a transição, ou você pode migrar manualmente para ter controle total.
---

> **For AI agents:** the complete documentation index is at [llms.txt](https://jamdesk.com/docs/llms.txt). Append `.md` to any page URL for its markdown version.



  Veja a versão em Markdown limpo desta página em https://jamdesk.com/docs/setup/migration.md





Os projetos do Mintlify têm um caminho de um comando: `jamdesk migrate` lê `mint.json`, grava `docs.json` e reescreve seu MDX diretamente. Está migrando do GitBook, Docusaurus, ReadMe, Confluence ou de outro lugar? A aba "Other Platforms" apresenta as etapas manuais. Elas são curtas se você conseguir exportar seu conteúdo como Markdown.

<YouTube id="DvIHWeBliK0" />

<Info>
**Exporte primeiro como Markdown, se possível.** O Jamdesk é baseado em MDX, portanto qualquer conteúdo que já esteja em Markdown pode ser incluído apenas renomeando a extensão para `.mdx` e adicionando algumas linhas de frontmatter.
</Info>

## Escolha seu caminho

### From Mintlify

A CLI faz a maior parte do trabalho para você.

<Card title="Guia do Mintlify para o Jamdesk" icon="book-open" href="https://jamdesk.com/blog/migrating-from-mintlify-to-jamdesk">
  Leia o guia passo a passo da migração, com contexto, exemplos e dicas.
</Card>

### Migração automatizada

#### 1. Instale a CLI

```bash
npm install -g jamdesk
```

#### 2. Execute a migração

```bash
jamdesk migrate
```

Na raiz do projeto, isso é executado de uma só vez:

- Lê `mint.json` e grava `docs.json`
- Renomeia componentes obsoletos nos arquivos MDX (por exemplo, `CardGroup` → `Columns`)
- Move arquivos MDX de snippets órfãos para `/snippets/` e reescreve todas as importações relativas ao diretório pai (`../foo/bar.mdx`) para importações relativas à raiz (`/snippets/foo/bar.mdx`)
- Extrai componentes inline que usam hooks do React para `/snippets/<name>.tsx` com a diretiva `'use client'` e reescreve o MDX original para importar de `/snippets/`
- Corrige automaticamente problemas mecânicos de sintaxe MDX que causariam falha no build

O comando é idempotente: execute-o novamente após fazer edições, e ele processará apenas o que for novo. Tudo o que não puder tratar automaticamente com segurança será exibido como um aviso, com o arquivo, a importação e a ação a realizar.

#### 3. Revise e ajuste

Verifique os arquivos `docs.json` e MDX gerados. Confirme a estrutura de navegação e todos os avisos exibidos pela CLI.

### Mapeamento de configuração

A CLI converte `mint.json` para `docs.json` automaticamente. Estas são as principais diferenças para que você possa verificar o resultado.

**Mintlify (`mint.json`):**

```json
{
  "name": "My Docs",
  "navigation": [
    { "group": "Getting Started", "pages": ["introduction", "quickstart"] }
  ],
  "colors": { "primary": "#0D9373" },
  "topbarLinks": [{ "name": "Blog", "url": "https://example.com/blog" }]
}
```

**Jamdesk (`docs.json`):**

```json
{
  "$schema": "https://jamdesk.com/docs.json",
  "name": "My Docs",
  "theme": "jam",
  "colors": { "primary": "#0D9373" },
  "navbar": {
    "links": [{ "label": "Blog", "href": "https://example.com/blog" }]
  },
  "navigation": {
    "groups": [
      { "group": "Getting Started", "pages": ["introduction", "quickstart"] }
    ]
  }
}
```

### Compatibilidade de componentes

A maioria dos componentes do Mintlify tem equivalentes diretos no Jamdesk. Alguns têm nomes ou sintaxe diferentes.

| Componente do Mintlify | Equivalente no Jamdesk | Observações |
|---|---|---|
| `<Card>` | `<Card>` | Mesma sintaxe |
| CardGroup | `<Columns>` | Use a prop `cols` para definir o número de colunas |
| `<Columns>` | `<Columns>` | Mesma sintaxe |
| `<Accordion>` | `<Accordion>` | Mesma sintaxe |
| `<Tabs>` / `<Tab>` | `<Tabs>` / `<Tab>` | Mesma sintaxe |
| `<Steps>` / `<Step>` | `<Steps>` / `<Step>` | Mesma sintaxe |
| `<CodeGroup>` | `<CodeGroup>` | Mesma sintaxe |
| `<Tip>`, `<Note>`, `<Warning>` | `<Tip>`, `<Note>`, `<Warning>` | Mesma sintaxe |
| `<ResponseField>` | `<ParamField>` | Nome diferente |
| `<Snippet>` | Importar de `/snippets/` | Abordagem diferente |

### Problemas comuns

#### CardGroup becomes Columns

`jamdesk migrate` renomeia `CardGroup` para `Columns` em todos os arquivos MDX. A prop `cols` é mantida sem alterações. Verifique todos os arquivos que você editou após executar a migração.

#### ResponseField becomes ParamField

Renomeie `<ResponseField>` para `<ParamField>`. As props permanecem iguais.

```mdx
{/* Before */}
<ResponseField name="id" type="string" required>
  The unique identifier
</ResponseField>

{/* After */}
<ParamField name="id" type="string" required>
  The unique identifier
</ParamField>
```

#### Snippets are relocated and rewired automatically

O Jamdesk resolve apenas importações raiz-relativas de `/snippets/*`. Os projetos do Mintlify geralmente mantêm arquivos MDX de snippets em qualquer lugar da árvore e os importam usando caminhos relativos ao diretório pai (`import X from '../shared/x.mdx'`).

`jamdesk migrate` faz três coisas aqui em uma única execução:

- Detecta arquivos MDX importados como snippets, mas localizados fora de `/snippets/`, e move-os para `/snippets/`, preservando o caminho relativo (assim, snippets com prefixo de localidade, como `de/foo.mdx`, não entram em conflito).
- Reescreve todas as importações de snippets relativas ao diretório pai em todos os arquivos MDX para o novo caminho relativo à raiz.
- Extrai qualquer componente inline que use hooks do React para um arquivo `'use client'` em `/snippets/<name>.tsx` e substitui a exportação inline por uma importação de `/snippets/`.

Se você usou o elemento JSX `<Snippet file="my-snippet.mdx" />` do Mintlify, substitua-o por uma importação MDX. Esse elemento não é reescrito automaticamente:

```mdx
{/* Before (Mintlify) */}
<Snippet file="my-snippet.mdx" />

{/* After (Jamdesk) */}
import MySnippet from '/snippets/my-snippet.mdx'

<MySnippet />
```

O relocador é conservador. Se o projeto não tiver uma navegação resolvida ou se as movimentações planejadas excederem `max(5, 25%)` de todos os arquivos MDX, ele será interrompido sem alterar nada e informará o motivo. Execute-o novamente depois de corrigir o motivo da interrupção.

#### topbarLinks maps to navbar.links

`topbarLinks` e `topbarCtaButton` do Mintlify são mapeados para `navbar.links` em `docs.json`. O campo `name` se torna `label`, e `url` se torna `href`.

### From Other Platforms

Para GitBook, ReadMe, Docusaurus, Confluence, Notion ou outras ferramentas de documentação.

<Card title="Conversor de HTML para MDX" icon="file-code" href="https://jamdesk.com/utilities/html-to-mdx" horizontal>
  Está exportando de uma plataforma que fornece HTML, como Confluence, Notion e muitas outras? Cole o conteúdo no conversor gratuito de HTML para MDX para obter MDX limpo que você pode incluir diretamente no projeto.
</Card>

<Tip>
  Precisa de ajuda com sua migração? [Fale conosco](mailto:contact@jamdesk.com) e ajudaremos você a configurar tudo.
</Tip>

### Do GitBook

O GitBook armazena o conteúdo como Markdown, com um arquivo `SUMMARY.md` para a navegação.

#### 1. Exporte seu conteúdo

Exporte seu espaço do GitBook como Markdown. Se você estiver usando a sincronização Git do GitBook, seu conteúdo já estará em um repositório Git como arquivos `.md`.

#### 2. Converta os arquivos para MDX

Renomeie os arquivos `.md` para `.mdx` e adicione frontmatter a cada arquivo:

```mdx
---
title: Your Page Title
description: A short description of the page
---

Your existing Markdown content here.
```

#### 3. Mapeie a navegação de SUMMARY.md

O GitBook usa `SUMMARY.md` para definir sua barra lateral. Converta-o em grupos de navegação no `docs.json`.

**GitBook (`SUMMARY.md`):**

```markdown
# Summary

## Getting Started
* [Introduction](introduction.md)
* [Quick Start](quickstart.md)

## API Reference
* [Authentication](api/auth.md)
```

**Jamdesk (`docs.json`):**

```json
{
  "navigation": {
    "groups": [
      {
        "group": "Getting Started",
        "pages": ["introduction", "quickstart"]
      },
      {
        "group": "API Reference",
        "pages": ["api/auth"]
      }
    ]
  }
}
```

#### 4. Mova as imagens

Mova todas as imagens para um diretório `/images` e atualize as referências nos arquivos MDX para usar caminhos absolutos, por exemplo, `/images/screenshot.png`.

#### 5. Teste localmente

```bash
jamdesk dev
```

### Do Docusaurus

Os projetos do Docusaurus já usam MDX, portanto a maior parte do conteúdo é transferida diretamente.

#### 1. Copie seus arquivos MDX

Copie o conteúdo do diretório `docs/` do Docusaurus para a raiz do projeto Jamdesk. Mantenha a estrutura de diretórios existente.

#### 2. Limpe o frontmatter

Remova os campos de frontmatter específicos do Docusaurus. Mantenha `title` e `description` e exclua os demais.

```yaml
---
# Remove these Docusaurus fields
sidebar_position: 3
sidebar_label: "Custom Label"
slug: /custom-url
pagination_next: null

# Keep these
title: Your Page Title
description: A short description
---
```

#### 3. Mapeie sidebars.js para docs.json

Converta a estrutura de categorias de `sidebars.js` em grupos de navegação no `docs.json`.

**Docusaurus (`sidebars.js`):**

```javascript
module.exports = {
  docs: [
    {
      type: 'category',
      label: 'Getting Started',
      items: ['intro', 'installation'],
    },
  ],
};
```

**Jamdesk (`docs.json`):**

```json
{
  "navigation": {
    "groups": [
      {
        "group": "Getting Started",
        "pages": ["intro", "installation"]
      }
    ]
  }
}
```

#### 4. Substitua os componentes do Docusaurus

Substitua os componentes específicos do Docusaurus pelos equivalentes do Jamdesk.

| Docusaurus | Jamdesk | Exemplo |
|---|---|---|
| `:::note` / `:::tip` / `:::warning` | `<Note>` / `<Tip>` / `<Warning>` | Consulte [componentes de destaque](https://jamdesk.com/docs/pt/components/overview) |
| `import Tabs from '@theme/Tabs'` | `<Tabs>` (disponível globalmente) | Não é necessária nenhuma importação |
| `import TabItem from '@theme/TabItem'` | `<Tab>` (disponível globalmente) | Use `title` em vez de `label` |

#### 5. Teste localmente

```bash
jamdesk dev
```

### De outras ferramentas

Para Confluence, Notion, ReadMe ou qualquer outra plataforma, o processo é o mesmo: coloque seu conteúdo em Markdown e configure a estrutura do projeto Jamdesk.

#### 1. Exporte como Markdown

A maioria das plataformas oferece uma opção de exportação para Markdown ou HTML. Use Markdown quando disponível. Para HTML, converta para Markdown usando uma ferramenta como o [Pandoc](https://pandoc.org/).

```bash
# Convert HTML to Markdown with Pandoc
pandoc input.html -f html -t markdown -o output.md
```

#### 2. Crie docs.json

Comece com uma configuração mínima e desenvolva sua navegação à medida que adicionar páginas.

#### 3. Converta os arquivos para MDX

Renomeie os arquivos `.md` para `.mdx` e adicione frontmatter (`title`, `description`) a cada arquivo.

#### 4. Mova os assets

Mova as imagens e outros assets para um diretório `/images`. Atualize as referências aos arquivos para usar caminhos absolutos.

#### 5. Teste localmente

```bash
jamdesk dev
```

## Checklist pós-migração

<Check>Todas as páginas são renderizadas sem erros</Check>
<Check>A estrutura de navegação corresponde à do site original</Check>
<Check>Os links internos funcionam corretamente</Check>
<Check>As imagens e os assets são exibidos corretamente</Check>
<Check>Os blocos de código usam o realce de sintaxe correto</Check>
<Check>A pesquisa indexa seu conteúdo</Check>

## O que vem a seguir?

<Columns cols={2}>
  <Card title="Estrutura de diretórios" icon="folder-tree" href="/pt/setup/directory-structure">
    Saiba como organizar sua documentação
  </Card>
  <Card title="Referência de docs.json" icon="gear" href="/pt/config/docs-json-reference">
    Configure as definições do seu site
  </Card>
</Columns>