Jamdesk Documentation logo

Guia de migração

Migre um projeto Mintlify com jamdesk migrate, que converte mint.json em docs.json e reescreve os arquivos MDX no próprio local.

Migre um projeto Mintlify com um único comando: jamdesk migrate lê mint.json, grava docs.json e reescreve os arquivos MDX no próprio local. Para GitBook, Docusaurus, ReadMe, Confluence ou outra plataforma, siga as etapas manuais na aba "Outras plataformas".

Se puder, exporte primeiro como Markdown. O Jamdesk é baseado em MDX. Basta renomear um arquivo Markdown para .mdx e adicionar algumas linhas de frontmatter.

Escolha seu caminho

Guia de migração do Mintlify para o Jamdesk

Guia de migração com contexto, exemplos e dicas.

Migração automatizada

1
Instale a CLI
npm install -g jamdesk
2
Execute a migração
jamdesk migrate

Execute o comando na raiz do projeto. Ele faz o seguinte:

  • Lê mint.json e grava docs.json
  • Renomeia componentes obsoletos nos arquivos MDX (por exemplo, CardGroup → Columns)
  • Move arquivos MDX de snippets sem referência para /snippets/ e reescreve todas as importações relativas ao diretório pai (../foo/bar.mdx) para caminhos relativos à 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 as edições para processar apenas o que há de novo. Tudo o que não puder corrigir com segurança será exibido como aviso, com o arquivo, a importação e a ação necessária.

3
Revise e ajuste

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

Mapeamento de configuração

A CLI converte mint.json em docs.json. Use estas diferenças para verificar o resultado.

Mintlify (mint.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):

{
  "$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 MintlifyEquivalente no JamdeskObservações
<Card><Card>Mesma sintaxe
CardGroup<Columns>Use a propriedade 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>Importação de /snippets/Abordagem diferente

Problemas comuns

jamdesk migrate renomeia CardGroup para Columns em todos os arquivos MDX. A propriedade cols é mantida sem alterações. Confira os arquivos editados após executar a migração.

Renomeie <ResponseField> para <ParamField>. As propriedades permanecem iguais.

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

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

O Jamdesk resolve apenas importações /snippets/* relativas à raiz. Em projetos Mintlify, os arquivos MDX de snippets costumam estar em qualquer lugar da árvore e ser importados com caminhos relativos ao diretório pai (import X from '../shared/x.mdx').

jamdesk migrate corrige isso:

  • Move para /snippets/ os arquivos MDX importados como snippets que estejam fora desse diretório. Mantém o caminho relativo para evitar colisões entre snippets com prefixo de localidade, como de/foo.mdx.
  • Reescreve todas as importações de snippets relativas ao diretório pai em todos os arquivos MDX para usar 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/.

Substitua o elemento JSX <Snippet file="my-snippet.mdx" /> do Mintlify por uma importação MDX. A CLI não o reescreve:

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

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

<MySnippet />

O processo de realocação é interrompido sem alterar nada se o projeto não tiver navegação resolvida ou se as mudanças planejadas excederem max(5, 25%) de todos os arquivos MDX. O motivo é exibido. Corrija o problema e execute novamente.

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

Checklist pós-migração

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

O que vem a seguir?

Estrutura de diretórios

Saiba como organizar sua documentação

Referência de docs.json

Configure as definições do seu site