Instalação da CLI

Instale a CLI para visualizar e desenvolver sua documentação localmente

Instalando a CLI

Pré-requisito: Instale o Node.js antes de continuar.

1. Instale a CLI.

   Execute o seguinte comando para instalar a CLI:

   npm

   npm i -g mint
   

2. Pré-visualize localmente.

   Vá até o diretório da sua documentação (onde o arquivo docs.json está localizado) e execute o seguinte comando:

   mint dev
   

   Uma pré-visualização local da sua documentação estará disponível em http://localhost:3000.

Como alternativa, se você não quiser instalar a CLI globalmente, você pode executar um script único:

npx mint dev

Atualizações

Se sua visualização local estiver diferente do que você vê na web na versão de produção, atualize sua CLI local:

mint update

Se o comando mint update não estiver disponível na sua versão local, reinstale a CLI na versão mais recente:

npm

npm i -g mint@latest

Portas personalizadas

Por padrão, a CLI usa a porta 3000. Você pode personalizar a porta usando a opção --port. Para executar a CLI na porta 3333, por exemplo, use este comando:

mint dev --port 3333

Se você tentar executar em uma porta que já está em uso, ela usará a próxima porta disponível:

A porta 3000 já está em uso. Tentando a 3001.

Visualizando como um grupo específico

Se você usa Autenticação parcial para restringir o acesso à sua documentação, pode visualizar como um grupo de autenticação específico usando a flag --group [groupname].

Por exemplo, se você tem um grupo chamado admin, é possível visualizar como membro desse grupo com o comando:

mint dev --group admin

Comandos adicionais

Embora mint dev seja o comando mais utilizado, há outros comandos que você pode usar para gerenciar sua documentação.

Encontrar links quebrados

A CLI pode ajudar a validar links de referência na sua documentação. Para identificar links quebrados, use o seguinte comando:

mint broken-links

Verificando a especificação OpenAPI

Você pode usar a CLI para verificar erros no seu arquivo OpenAPI com o seguinte comando:

mint openapi-check <openapiFilenameOrUrl>

Você pode informar um nome de arquivo (por exemplo, ./openapi.yaml) ou uma URL (por exemplo, https://petstore3.swagger.io/api/v3/openapi.json).

Renomeando arquivos

Você pode renomear arquivos e atualizar todas as suas referências usando o seguinte comando:

mint rename <oldFilename> <newFilename>

Migrando páginas de endpoint em MDX

Você pode migrar páginas de endpoint em MDX para páginas geradas automaticamente a partir da sua especificação OpenAPI usando o seguinte comando:

mint migrate-mdx

Este comando converte páginas de endpoint em MDX individuais em páginas geradas automaticamente definidas no seu docs.json, move o conteúdo em MDX para a extensão x-mint na sua especificação OpenAPI e atualiza a navegação. Consulte Migração a partir de MDX para obter informações detalhadas.

Formatação

Durante o desenvolvimento local, recomendamos usar extensões no seu IDE para reconhecer e formatar arquivos MDX.

Se você usa Cursor, Windsurf ou VS Code, recomendamos a extensão MDX para VS Code para destaque de sintaxe e o Prettier para formatação de código.

Se você usa JetBrains, recomendamos o plugin MDX para IntelliJ IDEA para destaque de sintaxe e a configuração do Prettier para formatação de código.

Solução de problemas

Erro: Não foi possível carregar o módulo "sharp" usando o runtime darwin-arm64

Isso pode ocorrer devido a uma versão desatualizada do Node. Tente o seguinte:

1. Remova a versão do CLI do mint atualmente instalada: npm uninstall -g mint
2. Atualize para o Node.js.
3. Reinstale o CLI do mint: npm install -g mint

Problema: Erro desconhecido

Solução: Vá até o diretório raiz do seu dispositivo e exclua a pasta ~/.mintlify. Depois, execute mint dev novamente.

Erro: permissão negada

Isso acontece por falta de permissões para instalar pacotes do Node globalmente.

Solução: Tente executar sudo npm i -g mint. Você será solicitado a informar sua senha, a mesma que usa para desbloquear o computador.

A prévia local não está igual à minha documentação na web

Isso provavelmente se deve a uma versão desatualizada do CLI.

Solução: Execute mint update para obter as atualizações mais recentes.

mintlify vs. pacote mint

Se você tiver qualquer problema com o pacote do CLI, primeiro execute npm ls -g. Esse comando mostra quais pacotes estão instalados globalmente na sua máquina.

Se você não usa npm ou não o vê na lista com -g, tente which mint para localizar a instalação.

Se você tiver um pacote chamado mint e um pacote chamado mintlify instalados, desinstale o mintlify.

1. Desinstale o pacote antigo:

  npm uninstall -g mintlify

2. Limpe o cache do npm:

  npm cache clean --force

3. Reinstale o novo pacote:

npm i -g mint