Guia de migração
Migrando de outra plataforma de documentação? O Jamdesk pode automatizar a transição, ou você pode migrar manualmente para ter controle total.
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.
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.
Escolha seu caminho
A CLI faz a maior parte do trabalho para você.
Migração automatizada
npm install -g jamdeskjamdesk migrateNa raiz do projeto, isso é executado de uma só vez:
- Lê
mint.jsone gravadocs.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>.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 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.
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):
{
"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 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
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.
Renomeie <ResponseField> para <ParamField>. As props 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 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, comode/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>.tsxe 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:
{/* 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 e topbarCtaButton do Mintlify são mapeados para navbar.links em docs.json. O campo name se torna label, e url se torna href.