Nextra ti consente di creare un sito in pochi minuti, quindi è perfetto per distribuire documenti al tuo team.

Se hai familiarità con Next.js, puoi usarlo per sviluppare facilmente un sito di documentazione. Il framework Nextra si prende cura del nocciolo per te; tutto ciò che devi fare è aggiungere Markdown o contenuto HTML e dati YAML o JSON.

Esegui questi passaggi per creare un sito di documentazione utilizzando Nextra, un generatore di siti statici basato su Next.js. Installerai e configurerai le dipendenze necessarie, quindi imparerai come aggiungere nuovi documenti e pagine, scrivere Markdown e includere componenti React.

Requisiti per la creazione di un sito Doc con Nextra

Inizia installando Node.js se non l'hai già fatto. IL ultima versione di Node.js viene fornito con npm, il gestore di pacchetti del nodo, di cui avrai bisogno per installare le dipendenze per questo progetto.

Oltre a Node.js, dovrai installare Idiota. È necessario Git per distribuire il sito su pagine GitHub, Netlify o un altro provider di hosting. Avrai anche bisogno di un editor di codice avanzato, come VS Code.

instagram viewer

Installazione di Nextra

Puoi usare un modello di documenti nextra per avviare un sito di documentazione. Avvia un prompt dei comandi e vai alla directory in cui vuoi configurare il tuo progetto. Quindi eseguire il seguente comando per eseguire il bootstrap del sito della documentazione:

clone di git https://github.com/shuding/nextra-docs-template

Questo comando eseguirà lo scaffolding di un'applicazione all'interno della directory corrente. Successivamente, esegui il seguente comando per installare le dipendenze:

cd nextra-docs-template
installazione npm

Al termine dell'installazione, avviare l'applicazione. Fallo eseguendo il seguente comando sul tuo terminale:

npm esegue lo sviluppo

Questo comando avvia un server di sviluppo su localhost: 3000. Segui il link sul tuo terminale per visualizzare il sito della documentazione. La home page dovrebbe essere simile a questa:

Se guardi sul lato sinistro della pagina, troverai le pagine denominate introduzione E Un'altra pagina. Sotto questi collegamenti di pagina, troverai una pagina chiamata Satori, annidata all'interno del file Avanzato (una cartella) directory. Infine, nell'area di navigazione, troverai i link al Di E Contatto pagine.

Per capire come funzionano queste pagine, devi prima capire come Next.js esegue il rendering delle pagine.

Comprensione della struttura della directory

Poiché Nextra utilizza il framework Next.js, esegue il rendering di ogni file nel formato pagine/ cartella come una pagina separata.

Dentro il pagine directory, troverai quattro file modello: about.mdx, avanzato.mdx, un altro.mdx, E index.mdx. Ciascuno di questi file corrisponde a una pagina del sito web; Per esempio, index.mdx corrisponde alla home page. L'URL host locale: 3000/circa corrisponde a about.mdx, e così via.

Dentro pagine, c'è anche una cartella denominata Avanzate, che ospita un singolo file denominato satori.mdx. L'URL per questo file sarà localhost: 3000/avanzato/satori.

Nota come ciascuno di questi file termina con a .mdx estensione.

Che cos'è l'MDX?

Se hai esperienza con React, dovresti conoscere JSX. Questo è un linguaggio simile a HTML che puoi usare per descrivere l'interfaccia utente dei componenti React.

MDX carica, analizza e rende JSX in un documento Markdown. Grazie a MDX, puoi scrivere componenti React e importarli nei tuoi documenti Markdown quando necessario. I file MDX terminano con l'estensione .mdx e possono includere sia Markdown che JSX.

MDX ti consente di combinare la tua conoscenza di Markdown con React per creare componenti riutilizzabili. Puoi creare moduli CSS per modellare i componenti. Questo ti aiuta a organizzare i tuoi componenti per migliorare la leggibilità e la manutenibilità.

Come modificare le pagine esistenti nel sito della documentazione

Per modificare una pagina esistente, apri semplicemente il file corrispondente e apporta le modifiche. Le lingue supportate sono Markdown e JSX.

Ad esempio, apri il file index.mdx file e sostituisci il contenuto con questo:

# Benvenuto nella mia documentazione
Sono felice di vederti qui. Grazie
## I miei social
Seguimi su [Cinguettio](https://twitter.com/kingchuuks) E [Linkedin](https://linkedin.com/in/kingchuks)

Questo esempio utilizza Markdown per formattare il contenuto. Contiene un'intestazione di livello uno, un'intestazione di livello due e due collegamenti ai social media.

Salva il file e visita la home page del tuo sito di documentazione. La pagina dovrebbe ora apparire così:

In fondo alla pagina trovi anche la data dell'ultimo aggiornamento del documento.

Aggiunta di una nuova pagina

Prima di aggiungere una nuova pagina, devi prima decidere se la pagina sarà nel file pagine/ directory o all'interno di una cartella al suo interno. Usa le cartelle se vuoi categorizzare le tue pagine o sviluppare una gerarchia.

In questo caso, crea una pagina autonoma al livello superiore. Apri un file chiamato installazione.mdx nel tuo editor di codice e incolla il seguente codice Markdown al suo interno:

# Guida d'installazione
Segui questa guida per installare il mio pacchetto nel tuo progetto
## 1. Installa Node.js
Per installare Node.js, visita il
[Sito della documentazione Node.js](https://nodejs.org/en/download)

Salva il file e controlla il browser. Troverai l'etichetta Installazione nel menu laterale. Quando si fa clic sul collegamento, il contenuto di installazione.mdx rende sulla pagina:

Puoi modificare l'etichetta ed eseguire altre configurazioni nel file _meta.json all'interno della directory delle pagine. Per saperne di più su questo, fare riferimento al Organizza i file sezione di La documentazione di Nextra.

Utilizzo dei componenti React

I file MDX possono includere JSX, che è il linguaggio utilizzato da React. Puoi creare un componente all'interno della cartella dei componenti e importarlo in uno qualsiasi dei documenti del tuo sito.

Puoi vedere un esempio di come puoi incorporare componenti in Markdown nel file un altro.mdx file:

## Componente
importa {useState} da 'reagire'
importa stili da '../components/counters.module.css'
export const Contatore = () => { 
 const [count, setCount] = useState (0); 


 ritorno( 


 Clic {count} volte


)
}

<Contatore />

## Componenti esterni
importa contatori da '../components/contatori'

<Contatori />

Questo file Markdown contiene una definizione per il componente Counter. Successivamente, importa il componente Contatori dal file componenti directory.

Se hai intenzione di utilizzare lo stesso componente nel tuo sito di documentazione, è meglio crearlo come componente autonomo e importarlo quando ne hai bisogno.

Ulteriori informazioni su Markdown

Per creare contenuti per il tuo sito di documentazione, devi sapere come utilizzare Markdown. La buona notizia è che la sintassi Markdown è abbastanza facile da imparare. Quando combini la tua conoscenza di Markdown con React, puoi creare siti di documentazione davvero robusti.