Crea e Personalizza un Sito Docusaurus (con una Sezione Blog)

Per siti web leggeri, applicazioni e altri piccoli progetti, sempre più sviluppatori si rivolgono ai generatori di siti statici piuttosto che a WordPress o ad altri sistemi di gestione dei contenuti (CMS). I siti statici offrono un modo semplice ed efficace per creare siti web e applicazioni veloci, sicuri e facili da mantenere.

Docusaurus è uno di questi generatori di siti statici e sta rapidamente guadagnando popolarità nella comunità degli sviluppatori.

In questo articolo, faremo un’immersione profonda nei vantaggi dell’uso di Docusaurus come generatore di siti statici e perché è uno dei preferiti da chi lavora nello sviluppo.

Cos’È Docusaurus?

Docusaurus è un popolare generatore di siti statici che usa React, una delle principali librerie JavaScript, come libreria UI per la creazione delle pagine. Come altri generatori di questo tipo, è facile da configurare e da modificare e, soprattutto, vi fornisce tutto ciò di cui avete bisogno per creare un fantastico sito web statico.

Ciò che distingue Docusaurus, tuttavia, è che vi aiuta a creare e gestire un sito web in cui i contenuti giocano un ruolo fondamentale. Vi permette di creare in modo semplice e veloce un sito web completo, con tanto di blog, che mette in risalto i vostri contenuti fin dall’inizio.

Poiché i contenuti sono al centro della scena, Docusaurus è perfetto per creare siti di documentazione come i wiki. Utilizza anche il markdown, ideale sia per la collaborazione che per l’archiviazione in un repository git. Inoltre, ha un sacco di funzioni incredibili come l’i18n, la ricerca e i temi personalizzati, di cui parleremo in dettaglio più avanti.

Ecco solo alcune delle caratteristiche che rendono Docusaurus una valida opzione:

• Costruito con React.
• Supporto per MDX v1.
• Supporto per l’incorporazione di componenti React tramite Markdown.
• Versionamento dei documenti.
• Compatibilità con Git, Crowdin e altri gestori di traduzione per la traduzione dei documenti e la distribuzione in blocco o individuale

Chi Usa Docusaurus?

Docusaurus è stato creato da Facebook, quindi non c’è da sorprendersi se attualmente viene utilizzato da molti grandi marchi e aziende del web.

Ecco solo alcuni dei più grandi marchi che usano Docusaurus oggi (e altri ne arriveranno presto, dato che la popolarità di Docusaurus continua a crescere):

• Algolia DocSearch
• Jest
• React Native
• Supabase

E ogni giorno se ne aggiungono altri.

Come Installare Docusaurus

Docusaurus è molto semplice da installare e richiede solo pochi minuti. In questo tutorial realizzeremo un sito di documentazione con un blog e personalizzeremo l’aspetto del sito.

Ed ecco la parte più bella: ci vorrà meno di un’ora per avviare il tutto.

Cominciamo!

Requisiti

Docusarus richiede Node.js 16.14 o versioni successive. Si tratta di un SSG flat-file, il che significa che non avrete bisogno di un database aggiuntivo.

Se non avete già a disposizione Node.js 16.14+, dovrete iniziare installando Node.js o aggiornando la vostra versione attuale. Poi potrete passare al processo di installazione di Docusaurus che trovate qui sotto.

Useremo anche il sito Docusaurus di esempio di questo repository GitHub. Potete usare questo sito o un’installazione pulita di Docusaurus per seguire il tutorial.

Processo di Installazione

Per iniziare il processo di installazione di Docusaurus, dovete prima eseguire il seguente comando:

npx create-docusaurus@latest  classic

In questo modo verrà creata una cartella per il vostro progetto e al suo interno verrà inserito il tema classico. Il tema classico contiene già alcune funzionalità preconfigurate come un blog, pagine personalizzate e un framework CSS.

Dopo l’installazione, dovrete eseguire il seguente comando per avviare il server locale:

npm start

Se volete creare una versione ottimizzata e pronta per la distribuzione, dovete invece eseguire questo comando:

npm run build

Struttura

Una volta installata l’istanza di Docusaurus, potrete aprire la cartella del progetto e dare un’occhiata allo “scheletro” del vostro nuovo sito.

Ecco come appare la struttura dei file:

my-website
├── blog
│ ├── 2019-05-28-hola.md
│ └── 2020-05-30-welcome.md
├── docs
│ ├── doc1.md
│ └── mdx.md
├── src
│ ├── css
│ │ └── custom.css
│ └── pages
│ ├── styles.module.css
│ └── index.js
├── static
│ └── img
├── docusaurus.config.js
├── package.json
├── README.md
├── sidebars.js
└── yarn.lock

Ci sono alcuni dettagli da notare riguardo ad alcuni di questi file e cartelle:

• /blog: Contiene tutti i file relativi al vostro blog.
• /docs: Contiene tutti i file relativi ai documenti. Potete personalizzare il loro ordine nel file sidebar.js.
• /src: Contiene tutti i file non legati alla documentazione, come le pagine o i componenti personalizzati.
• /src/pages: Tutti i file JSX/TSX/MDX saranno trasformati in pagine.
• /static: File statici che verranno copiati nella cartella di creazione finale.
• docusaurus.config.js: File di configurazione di Docusaurus.
• packaged.json: Ogni sito Docusaurus è un’applicazione React, quindi qui troverete tutte le dipendenze e gli script che usa React.
• sidebar.js: Qui potete specificare l’ordine dei documenti nella barra laterale.

Personalizzare l’Installazione di Docusaurus

Come potete vedere dalla semplicità della sua struttura di file, Docusaurus è facile da usare e da navigare. Allo stesso modo, personalizzare il vostro sito Docusaurus è un gioco da ragazzi. Potete aprire e modificare questi file usando il vostro editor di testo o IDE preferito.

Vediamo alcune delle opzioni di personalizzazione che avrete a disposizione fin da subito.

Homepage

La prima cosa che probabilmente vorrete fare è personalizzare la homepage predefinita per esporre il vostro progetto. Fortunatamente, non è complicato apportare modifiche alla homepage di Docusaurus.

Per modificare la homepage, aprite il file src/pages/index.js e apportate le modifiche direttamente lì. Si tratta di una tipica pagina React, quindi potete modificarla o ricostruirla cambiando il contenuto o creando componenti React personalizzati.

File di Configurazione

Successivamente, ci immergeremo nel file docusaurus.config.js e modificheremo alcuni dettagli importanti per la nostra istanza.

Nome e descrizione

Nel file di configurazione troverete:

const config = {
title: 'My Site',
tagline: 'Dinosaurs are cool',
url: 'https://your-docusaurus-site.com',
baseUrl: '/',

Modificate questi dettagli per adattarli alle esigenze del vostro sito e salvate il file.

Barra di navigazione

Per modificare la barra di navigazione, individuate la voce navbar.

Nel nostro esempio, vogliamo aggiungere un link a Kinsta, rinominare la voce “Tutorial” in “Documentazione iniziale” e aggiungere il logo di Kinsta.

Ecco come procedere:

navbar: {
  title: 'Kinsta starters',
  logo: {  
	alt: 'Kinsta Logo',
	src: 'img/kinsta-logo-alpha-purple.png',
  },
  items: [
	{
  	label: 'Kinsta starters',
  	to: '/docs/intro',
	},
	{to: '/blog', label: 'Blog', position: 'left'},
	{
  	href: 'https://github.com/kinsta',
  	label: 'GitHub',
  	position: 'right',
	},
  ],
},

Footer

La personalizzazione del footer in Docusaurus è composta da due sezioni: il contenuto del footer stesso e i link del footer.

Contenuto del footer

Il contenuto principale del footer (escluso l’elenco dei link) può essere collocato nel file themeConfig.footer. Questo è il punto ideale per aggiungere un logo e una nota di copyright.

Ecco come abbiamo modificato la configurazione del footer:

module.exports = {
  themeConfig: {
	footer: {
  	logo: {
    	alt: 'Kinsta Logo',
    	src: 'img/kinsta-logo.png',
    	href: 'https://kinsta.com',
    	width: 160,
    	height: 51,
  	},
  	copyright: `Copyright © ${new Date().getFullYear()} Kinsta. Built with Docusaurus.`,
	},
  },
};

Link del footer

La modifica dei link del footer è simile a quella della navbar superiore: trovate la sezione footer in docusaurus.config.js e modificatela in base alle vostre esigenze.

Ecco come abbiamo modificato la sezione footer:

footer: {
  style: 'dark',
  links: [
	{
  	title: 'Docs',
  	items: [
    	{
      	label: 'Kinsta starters',
      	to: '/docs/intro',
    	},
  	],
	},
	{
  	title: 'Talk with us',
  	items: [
    	{
      	label: 'Discord',
      	href: 'https://discord.gg/vjRPMhFaBA',
    	},
    	{
      	label: 'Support',
      	href: 'https://kinsta.com/kinsta-support/',
    	},
    	{
      	label: 'Twitter',
      	href: 'https://twitter.com/kinsta',
    	},
  	],
	},
	{
  	title: 'More',
  	items: [
    	{
      	label: 'Application Hosting',
      	href: 'https://kinsta.com/application-hosting/',
    	},
    	{
      	label: 'Database Hosting',
      	href: 'https://kinsta.com/database-hosting/',
    	},
    	{
      	label: 'WordPress Hosting',
      	href: 'https://kinsta.com/wordpress-hosting/',
    	},
    	{
      	label: 'DevKinsta',
      	href: 'https://kinsta.com/devkinsta/',
    	},
  	],
	},
  ],
};

Colori e CSS

Il preset classico di Docusaurus utilizza il framework Infima CSS. Per questo motivo, i creatori di Docusaurus hanno creato un utilissimo strumento web per aiutarvi a modificare i colori e altri elementi e dichiarazioni CSS.

Una volta inserite le vostre preferenze nella pagina, lo strumento genererà un file custom.css – completo di una bella serie di tonalità complementari – in pochi secondi. Potrete quindi copiare questo nuovo file CSS nella cartella /src/css del vostro progetto per poterlo consultare.

Documentazione

Tutta la documentazione del vostro nuovo sito web è archiviata nella cartella /docs. Naturalmente, potete cambiare il nome della cartella in docusaurus.config.js.

Basta creare i file markdown nel vostro editor di testo o HTML e inserirli in quella cartella. Ogni file dovrebbe avere questo aspetto:

---
id: the-id
title: Title
---
# Rest of the document

In base all’ID, Docusaurus create gli URL per gli articoli in quella sottocartella: yourdomain.com/docs/{id}

Possiamo anche creare delle sottocartelle se vogliamo dividere la nostra documentazione in diverse sezioni logiche. Tuttavia, dovremo fare un po’ di lavoro aggiuntivo per far sì che queste sottocartelle funzionino come ci aspettiamo.

Supponiamo di creare una nuova cartella documenti chiamata “Starters”. Se poi aggiorniamo la homepage e facciamo clic sul nuovo link “Starters” aggiunto automaticamente alla nostra barra laterale, otterremo un errore perché non esiste ancora una pagina di indice nella nostra nuova cartella.

Il modo più semplice per risolvere questo problema è creare un file _category_.json che generi l’indice di tutte le pagine contenute in questa cartella. È sufficiente aggiungere il seguente codice:

{
  "label": "Starters",
  "position": 2,
  "link": {
	"type": "generated-index",
	"description": "All Kinsta Starters"
  },
};

Come potete vedere, la barra laterale si rigenera per adattarsi alla struttura dei vostri file. Questo perché il file sidebar.js contiene questo tutorialSidebar: [{type: 'autogenerated', dirName: '.'}],

Se poreferite occuparvi di questo aspetto in autonomia, potete cambiare il file con qualcosa di simile:

tutorialSidebar: [
  'intro',
  'hello',
  {
	type: 'category',
	label: 'Tutorial',
	items: ['tutorial-basics/create-a-document'],
  },
],

Blog

Docusaurus include un interessante modulo blog. Avere un blog accanto al vostro sito web principale può essere molto utile per informare la vostra base utenti sui cambiamenti che avvengono nel vostro progetto, oppure per mantenere le note del progetto come una forma di changelog.

Ogni articolo consiste in una parte frontale, come questa:

---
slug: docusaurus-starter
title: Docusaurus Starter
authors: palmiak
tags: [starters, docusaurus]
---

… e, naturalmente, il contenuto stesso. Dispone anche dell’utilissimo tag , che aiuta a limitare il riepilogo dell’articolo visualizzato in tutti gli elenchi di articoli.

È anche un’ottima idea creare un file authors.yml per i crediti. Il file ha questo aspetto:

palmiak:
name: Maciek Palmowski
title: DevRel
url: https://github.com/palmiak
image_url: https://github.com/palmiak.png

Grazie a questo file, avrete tutti i dati degli autori in un unico posto facile da consultare.

Come Distribuire il Vostro Sito Web Docusaurus su Kinsta

Oltre ai siti WordPress, alle applicazioni stand-alone e ai database, Kinsta può ospitare siti web statici.

Questo significa che è perfetto per i vostri siti Docusaurs e per gestire tutti i vostri progetti web direttamente dalla bacheca MyKinsta.

Una volta che la vostra applicazione è stata distribuita, potrete esaminare le analisi in corso della vostra applicazione, sia in tempo reale che storiche, con misurazioni che comprendono:

• Utilizzo della larghezza di banda.
• Tempo di creazione.
• Tempo di esecuzione.
• Utilizzo della CPU.
• Utilizzo della memoria.

Dall’inizio alla fine, il processo di distribuzione attraverso MyKinsta richiede solo pochi minuti.

Iniziamo!

Prerequisiti: Configurazione del Progetto Docusaurus

Per ospitare il vostro progetto Docusaurus sulla piattaforma di Application Hosting di Kinsta, dovrete:

1. Includere un campo nome nel vostro file package.json. (Questo campo può essere qualsiasi cosa e non influisce sulla distribuzione).
2. Includere uno script di compilazione nel file package.json. (Il vostro progetto Docusaurus dovrebbe già includerlo).
3. Installare il pacchetto serve npm e impostare lo script di avvio su serve build.

Una volta spuntate queste opzioni, potete passare alla distribuzione vera e propria del vostro sito.

Distribuire il Progetto Docusaurus

Seguite questi semplici passaggi per collegarvi al vostro account GitHub e lanciare il vostro sito Docusaurus:

1. Entrate nel vostro account MyKinsta e navigate nella scheda Applicazioni del menu di sinistra.
2. Fate clic sul pulsante blu Aggiungi servizio e scegliete Applicazione dal menu a tendina.

   

3. Se non avete ancora effettuato la connessione al vostro account GitHub tramite MyKinsta, vi verrà mostrato un messaggio che vi inviterà a farlo. Fate clic sul pulsante Continue with GitHub per procedere.

   

4. Si aprirà una nuova finestra che vi chiederà il permesso di autorizzare Kinsta ad accedere e gestire le vostre risorse GitHub. Verificate di aver effettuato l’accesso all’account GitHub corretto, quindi fate clic sul pulsante verde Authorize Kinsta in basso.

   

5. Ora siete arrivati alla procedura guidata per l’integrazione con GitHub. Questo è l’ultimo passo prima di poter distribuire il vostro sito. Esaminate attentamente i campi presentati e compilateli in base alla vostra configurazione di GitHub e ai requisiti del vostro progetto. Se avete un file Docker nel vostro repository, potete usarlo per impostare l’immagine del container; altrimenti, Kinsta imposterà automaticamente un’immagine del container per voi. Potreste dover modificare i permessi di GitHub prima di poter procedere, soprattutto se si tratta della vostra prima distribuzione tramite Kinsta.

   

   Potete scegliere se concedere a Kinsta l’accesso a tutti i repository o solo a quelli specifici. Questi permessi possono essere modificati in qualsiasi momento dalle impostazioni delle Applicazioni del vostro account GitHub.

   

6. Dopo aver effettuato le vostre scelte e averle confermate, vi verranno mostrati i dettagli della distribuzione e le opzioni per modificare le impostazioni (Change settings) o ripetere la distribuzione (Redeploy).

   

   In questa pagina troverete anche tutti gli errori che si sono verificati durante la distribuzione, insieme ai dettagli sulla causa del fallimento, in modo da poterli risolvere facilmente. Se avete difficoltà a risolvere il problema, potete trovare ulteriori indicazioni sugli errori di rollout nella documentazione di Kinsta.

   

Se siete arrivati fin qui senza errori, allora congratulazioni: avete appena distribuito con successo il vostro sito Docusaurus con Kinsta! La vostra applicazione (cioè il sito statico) sarà disponibile non appena avrete completato la procedura guidata. Potete visualizzarla all’URL della vostra applicazione, che di solito è https://your-docusaurus-site.kinsta.app.

Ecco la prima occhiata al nostro sito campione su Kinsta:

Riepilogo

Grazie alle sue funzioni sorprendentemente potenti, al design intuitivo, alla navigazione semplice e all’attenzione per i contenuti, non è difficile capire perché Docusaurus sia considerato uno strumento eccellente per qualsiasi professionista che voglia implementare e mantenere facilmente un sito e/o un blog di documentazione statica snello e ben organizzato.

Una volta che avrete riempito il vostro sito di contenuti che le persone apprezzeranno, inizierete a notare le ulteriori funzioni integrate che possono esservi utili. Per esempio, le funzionalità di ottimizzazione per i motori di ricerca di Docusaurus sono perfette per aiutarvi a ottenere una maggiore visibilità da parte di un pubblico più vasto mentre lavorate su altre tecniche per avanzare nel posizionamento SEO.

Avete realizzato qualcosa con Docusaurus? Condividete con noi i vostri progetti e le vostre esperienze nella sezione commenti qui sotto.

Maciek Palmowski

Maciek è un web developer che lavora in Kinsta come Development Advocate Analyst. Dopo l'orario di lavoro, passa la maggior parte del tempo a programmare, a cercare notizie interessanti per le sue newsletter o a bere caffè.