Guida rapida

Distribuisci la tua documentazione in pochi minuti

Questa guida rapida ti mostra come configurare e distribuire il tuo sito di documentazione in pochi minuti.

Al termine di questa guida, avrai un sito di documentazione online pronto per essere personalizzato ed esteso.

Prerequisiti: Prima di iniziare, crea un account e completa l’onboarding.

Per iniziare

Al termine dell’onboarding, il tuo sito di documentazione viene distribuito automaticamente a un URL univoco con il seguente formato:

https://<your-project-name>.mintlify.app

Trova il tuo URL nella pagina Overview della tua dashboard.

L’URL del tuo sito è disponibile subito. Usa questo URL per eseguire test e condividerlo con il tuo team mentre configuri il sito di documentazione.

Installa l’app GitHub

Mintlify offre un’app GitHub che automatizza il deployment quando esegui il push delle modifiche al tuo repository.

Installa l’app GitHub seguendo le istruzioni nella checklist di onboarding o dal tuo dashboard.

1. Vai su Settings nel tuo dashboard Mintlify.
2. Seleziona GitHub App dalla barra laterale.
3. Seleziona Install GitHub App. Si aprirà una nuova scheda con la pagina di installazione dell’app GitHub.
4. Seleziona l’organizzazione o l’account utente in cui desideri installare l’app.
5. Seleziona i repository che desideri collegare.

Aggiorna le autorizzazioni dell’app GitHub se sposti la documentazione in un repository diverso.

Autorizza il tuo account GitHub

1. Vai su Settings nella dashboard di Mintlify.
2. Seleziona My Profile dalla barra laterale.
3. Seleziona Authorize GitHub account. Si aprirà una nuova scheda con la pagina di autorizzazione di GitHub.

Un amministratore della tua organizzazione GitHub potrebbe dover autorizzare il tuo account, a seconda delle impostazioni dell’organizzazione.

Flussi di lavoro di editing

Mintlify offre due flussi di lavoro per creare e mantenere la documentazione:

Flusso di lavoro basato sul codice

Per chi preferisce lavorare con gli strumenti esistenti nel proprio ambiente locale. Clicca per passare a questa sezione.

Flusso di lavoro con editor web

Per chi preferisce un’interfaccia visiva nel browser. Clicca per passare a questa sezione.

Flusso di lavoro basato sul codice

Il flusso di lavoro basato sul codice si integra con l’ambiente di sviluppo esistente e con i repository Git. Questo approccio è ideale per i team tecnici che desiderano gestire la documentazione insieme al codice.

Installa la CLI

Per lavorare in locale sulla tua documentazione, installa la Command Line Interface (CLI), chiamata mint, eseguendo uno di questi comandi nel terminale:

npm

npm i -g mint

Devi avere Node.js installato sul tuo computer. Se riscontri problemi durante l’installazione, consulta la guida alla risoluzione dei problemi.

Modifica la documentazione

Dopo aver configurato l’ambiente, puoi iniziare a modificare i file della documentazione. Per esempio, aggiorna il titolo della pagina introduttiva:

1. Apri il repository creato durante l’onboarding.
2. Apri index.mdx e vai all’inizio del file:

index.mdx

---
title: "Introduction"
description: "This is the introduction to the documentation"
---

3. Aggiorna il campo title a "Hello World".

index.mdx

---
title: "Hello World"
description: "This is the introduction to the documentation"
---

Anteprima delle modifiche

Per visualizzare in locale l’anteprima delle modifiche, esegui il seguente comando:

mint dev

L’anteprima sarà disponibile su localhost:3000.

Effettua il push delle modifiche

Quando sei pronto a pubblicare le modifiche, esegui il push nel repository.

Mintlify rileva automaticamente le modifiche, crea la documentazione e distribuisce gli aggiornamenti sul sito. Monitora lo stato del deployment nella cronologia dei commit del repository GitHub o nella dashboard.

Al termine del deployment, l’ultimo aggiornamento sarà disponibile su <your-project-name>.mintlify.app.

Vai all'aggiunta di un dominio personalizzato

In alternativa, salta il flusso con l’Editor web e passa direttamente all’aggiunta di un dominio personalizzato.

Flusso di lavoro dell’Editor web

Il flusso di lavoro dell’Editor web offre un’interfaccia WYSIWYG (what you see is what you get) per creare e modificare la documentazione. Questo flusso di lavoro è ideale per chi preferisce lavorare direttamente nel browser senza dover utilizzare ulteriori strumenti di sviluppo locali.

Accedi all’Editor web

1. Accedi alla tua dashboard.
2. Seleziona Editor nella barra laterale sinistra.

Se non hai installato l’app GitHub, ti verrà richiesto di installarla quando apri l’Editor web.

Modifica la documentazione

Nell’Editor web puoi navigare tra i file della documentazione dalla barra laterale. Aggiorniamo la pagina introduttiva:

Trova e seleziona index.mdx nell’esplora file.

Quindi, nell’editor, aggiorna il campo Titolo in “Hello World”.

L’editor offre un set completo di strumenti di formattazione e componenti. Digita / nell’editor per aprire il menu dei comandi e accedere a questi strumenti.

Pubblica le modifiche

Quando sei soddisfatto delle modifiche, seleziona il pulsante Publish nell’angolo in alto a destra. Le modifiche vengono immediatamente pubblicate sul tuo sito di documentazione.

Usa i branch per visualizzare in anteprima e rivedere le modifiche tramite pull request prima di pubblicarle sul sito in produzione.

Per maggiori dettagli sull’uso dell’Editor web, inclusi branch e pull request per collaborare e visualizzare le modifiche in anteprima, consulta la nostra documentazione dell’Editor web.

Aggiunta di un dominio personalizzato

Sebbene il sottodominio <your-project-name>.mintlify.app funzioni bene per test e sviluppo, la maggior parte dei team preferisce utilizzare un dominio personalizzato per la documentazione in produzione.

Per aggiungere un dominio personalizzato, vai alla pagina Domain Setup nella dashboard.

Inserisci il tuo dominio (ad esempio docs.yourcompany.com) e segui le istruzioni fornite per configurare le impostazioni DNS con il tuo provider di dominio.

Le modifiche al DNS possono richiedere fino a 48 ore per propagarsi, anche se spesso si completano molto prima.

Prossimi passaggi

Congratulazioni! Hai pubblicato con successo il tuo sito di documentazione con Mintlify. Ecco i passaggi successivi consigliati per migliorare la tua documentazione:

Configura le impostazioni globali

Configura lo stile del sito, la navigazione, le integrazioni e altro ancora tramite il file docs.json.

Personalizza il tema

Scopri come personalizzare colori, caratteri e l’aspetto generale del tuo sito di documentazione.

Organizza la navigazione

Struttura la documentazione con una navigazione intuitiva per aiutare gli utenti a trovare ciò di cui hanno bisogno.

Aggiungi componenti interattivi

Migliora la tua documentazione con Componenti (Mintlify) interattivi come fisarmoniche, schede ed esempi di codice.

Configura i riferimenti API

Crea riferimenti API interattivi con specifiche OpenAPI e AsyncAPI.

Risoluzione dei problemi

Se riscontri problemi durante la configurazione, prova queste soluzioni comuni:

L'anteprima locale non funziona

Assicurati di avere installato Node.js v19+ e di eseguire il comando mint dev dalla directory che contiene il file docs.json.

Le modifiche non sono visibili sul sito live

Il deployment può richiedere alcuni minuti. Controlla le GitHub Actions (per i flussi di lavoro basati sul codice) o i log di deployment nella dashboard di Mintlify per verificare che non ci siano errori di build.

Il dominio personalizzato non si connette

Verifica che i record DNS siano configurati correttamente e attendi il tempo necessario per la propagazione (fino a 48 ore). Puoi usare strumenti come DNSChecker per verificare il record CNAME.