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
Migração automatizada
npm install -g jamdeskjamdesk migrateExecute o comando na raiz do projeto. Ele faz o seguinte:
- Lê
mint.jsone gravadocs.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>.tsxcom 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.
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 Mintlify | Equivalente no Jamdesk | Observaçõ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, comode/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>.tsxe 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.
