Passare da WordPress a Hugo

Quando è stato rilasciato WordPress 5, ero entusiasta di utilizzare l'editor Gutenberg per creare blocchi personalizzati, poiché i post sul mio blog personale avevano un paio di funzionalità che potevo trasformare in un blocco, semplificando la configurazione dei miei contenuti. Era sicuramente una cosa interessante da avere, eppure sembrava ancora piuttosto gonfio.

Più o meno nello stesso periodo, ho iniziato a leggere sempre di più sui generatori di siti statici e sul JAMstack (questo articolo di Chris Ferdinandi mi ha convinto). Con i progetti collaterali personali, puoi in qualche modo ignorare un'ampia varietà di problemi, ma come professionista, devi assicurarti di produrre la migliore qualità possibile. Prestazioni, sicurezza e accessibilità diventano le prime cose a cui pensare. Puoi sicuramente ottimizzare WordPress per essere abbastanza veloce, ma più veloce di un sito statico su una CDN che non ha bisogno di interrogare il database né generare la tua pagina ogni volta? Non così semplice.

Ho pensato di poterlo mettere in pratica con un mio progetto personale per imparare e poi poterlo utilizzare per progetti professionali, e forse anche qualcuno di voi vorrebbe sapere come fare. In questo articolo, esaminerò come ho effettuato la transizione da WordPress a uno specifico generatore di siti statici chiamato Hugo.

Hugo è costruito in Go, che è un linguaggio abbastanza veloce e facile da usare una volta che ti sarai abituato alla sintassi, che spiegherò. Tutto viene compilato localmente in modo da poter visualizzare in anteprima il tuo sito direttamente sul tuo computer. Il progetto verrà quindi salvato in un repository privato. Inoltre, ti guiderò attraverso come ospitarlo su Netlify e salvare le tue immagini su Git LFS (Large File Storage). Infine, daremo un'occhiata a come possiamo impostare un sistema di gestione dei contenuti per aggiungere post e immagini (simili al backend di WordPress) con Netlify CMS.

Nota che tutto questo è assolutamente gratuito, il che è piuttosto sorprendente se me lo chiedi (anche se dovrai pagare un extra se esaurisci tutto lo spazio di archiviazione LFS o se il traffico del tuo sito è intenso). Inoltre, sto scrivendo questo dal punto di vista dell'utente Bitbucket, in esecuzione su un Mac. Alcuni passaggi potrebbero essere leggermente diversi, ma dovresti essere in grado di seguirli, indipendentemente dalla configurazione che utilizzi.

Dovrai essere un po' a tuo agio con HTML, CSS, JS, Git e il terminale di comando. Anche avere alcune nozioni con linguaggi di creazione di modelli come Liquid potrebbe essere utile, ma esamineremo i modelli di Hugo per iniziare. Tuttavia, fornirò quanti più dettagli possibile!

So che sembra molto, e prima di iniziare a indagare su questo, lo era anche per me. Cercherò di rendere questa transizione il più agevole possibile per te scomponendo i passaggi. Non è molto difficile trovare tutte le risorse, ma c'è stato un po' di congetture da parte mia, passando da una documentazione all'altra.

1. Esportazione del contenuto da WordPress
2. Preparare il design del tuo blog
3. Configurazione di un nuovo repository
4. Attivazione di Git LFS (opzionale)
5. Creazione del sito su Netlify
6. Preparazione per Netlify Large Media (opzionale)
7. Configurare Hugo sul tuo computer
8. Creazione del tuo tema personalizzato
9. Note sulla sintassi di Hugo
10. Contenuto e dati
11. Distribuzione su Netlify
12. Configurazione di un dominio personalizzato
13. Modifica dei contenuti su Netlify CMS

Nota : se hai problemi con alcuni di questi, faccelo sapere nei commenti e cercherò di aiutarti, ma tieni presente che questo è destinato ad essere applicato a un blog semplice e statico che non ha una dozzina di widget o commenti (puoi impostarlo in seguito) e non un sito aziendale o un portfolio personale. Indubbiamente potresti, però, ma per semplicità, mi atterrò a un blog semplice e statico.

Prerequisiti

Prima di fare qualsiasi cosa, creiamo una cartella di progetto in cui risiederà tutto, dai nostri strumenti al nostro repository locale. Lo chiamerò "WP2Hugo" (sentiti libero di chiamarlo come vuoi).

Questo tutorial utilizzerà alcuni strumenti da riga di comando come npm e Git. Se non li hai già, installa quelli sulla tua macchina:

• Installa Git
• Installa Node.js e npm (Node.js include npm)
• Installa Homebrew (consigliato per utenti macOS/Linux)

Con questi installati, iniziamo!

1. Esportazione del contenuto da WordPress

Prima di tutto, dovremo esportare i tuoi contenuti da WordPress: post, pagine e caricamenti. Ci sono alcuni strumenti disponibili che Hugo menziona ma personalmente solo uno di loro ha funzionato: blog2md. Questo funziona eseguendo un file JavaScript con Node.js nel tuo terminale di comando. Prende i file XML esportati da WordPress e genera i file Markdown con la giusta struttura, convertendo il tuo HTML in Markdown e aggiungendo ciò che viene chiamato Front Matter, che è un modo per formattare i metadati all'inizio di ogni file.

Vai al tuo amministratore di WordPress e apri il menu Strumenti, sottomenu Esporta. Puoi esportare quello che vuoi da lì. Farò riferimento al file esportato come YOUR-WP-EXPORT.xml .

Puoi selezionare esattamente quali dati vuoi esportare dal tuo blog WordPress.

All'interno della nostra cartella WP2Hugo, ti consiglio di creare una nuova cartella denominata blog2md in cui collocherai i file dello strumento blog2md, così come la tua esportazione XML da WordPress ( YOUR-WP-EXPORT.xml ). Inoltre, crea una nuova cartella lì chiamata dove andranno out tuoi post di Markdown. Quindi, apri il tuo terminale di comando e naviga con il comando cd nella cartella "blog2md" appena creata (o digita cd con uno spazio e trascina la cartella nel terminale).

Ora puoi eseguire i seguenti comandi per ottenere i tuoi post:

 npm install node index.js w YOUR-WP-EXPORT.xml out

Cerca nella /WP2Hugo/blog2md/out per verificare se tutti i tuoi post (e le potenziali pagine) sono presenti. Se è così, potresti notare che c'è qualcosa sui commenti nella documentazione: avevo un blog senza commenti, quindi non avevo bisogno che fossero portati avanti, ma Hugo offre diverse opzioni per i commenti. Se hai commenti su WordPress, puoi esportarli per una successiva reimplementazione con un servizio specializzato come Disqus.

Se hai abbastanza familiarità con JS, puoi modificare il file index.js per cambiare il modo in cui i file dei tuoi post verranno modificati modificando la funzione wordpressImport . Potresti voler catturare l'immagine in primo piano, rimuovere il permalink, cambiare il formato della data o impostare il tipo (se hai post e pagine). Dovrai adattarlo alle tue esigenze, ma sappi che il ciclo ( posts.forEach(function(post){ ... }) ) attraversa tutti i post dell'esportazione, quindi puoi controllare il contenuto XML di ogni post in quel ciclo e personalizza il tuo argomento principale.

Inoltre, se hai bisogno di aggiornare gli URL contenuti nei tuoi post (nel mio caso, volevo rendere i collegamenti alle immagini relativi anziché assoluti) o la formattazione della data, questo è un buon momento per farlo, ma non perdere il sonno su di esso . Molti editor di testo offrono la modifica in blocco in modo da poter inserire un'espressione regolare e apportare le modifiche desiderate ai file. Inoltre, puoi eseguire lo script blog2md tutte le volte che è necessario, poiché sovrascriverà tutti i file già esistenti nella cartella di output.

Una volta che hai esportato i tuoi file Markdown, il tuo contenuto è pronto. Il prossimo passo è preparare il tuo tema WordPress per funzionare in Hugo.

2. Preparare il design del tuo blog

Il mio blog aveva un layout tipico con un'intestazione, una barra di navigazione, contenuto e barra laterale e un piè di pagina, abbastanza semplice da configurare. Invece di copiare parti del mio tema WordPress, l'ho ricostruito tutto da zero per assicurarmi che non ci fossero stili superflui o markup inutili. Questo è un buon momento per implementare nuove tecniche CSS ( pssst... Grid è davvero fantastico! ) e impostare una strategia di denominazione più coerente (qualcosa come le linee guida di CSS Wizardry). Puoi fare quello che vuoi, ma ricorda che stiamo cercando di ottimizzare il nostro blog, quindi è bene rivedere ciò che avevi e decidere se vale ancora la pena conservarlo.

Inizia suddividendo il tuo blog in parti in modo da poter vedere chiaramente cosa va dove. Questo ti aiuterà a strutturare il tuo markup e i tuoi stili. A proposito, Hugo ha la capacità integrata di compilare Sass in CSS, quindi sentiti libero di suddividere quegli stili in file più piccoli quanto vuoi!

Quando dico semplice, intendo davvero semplice.

In alternativa, puoi ignorare completamente questo passaggio per ora e modellare il tuo blog mentre procedi quando il tuo sito Hugo è configurato. Avevo il markup di base in atto e preferivo un approccio iterativo agli stili. È anche un buon modo per vedere cosa funziona e cosa no.

3. Configurazione di un nuovo repository

Ora che è fuori mano, dobbiamo impostare un repository. Suppongo che tu voglia creare un nuovo repository per questo, che sarà una grande opportunità per usare Git LFS (Large File System). Il motivo per cui ti consiglio di farlo ora è che l'implementazione di Git LFS quando hai già centinaia di immagini non è così semplice. L'ho fatto, ma era un mal di testa che probabilmente vorrai evitare. Ciò fornirà anche altri vantaggi lungo la strada con Netlify.

Mentre farò tutto questo tramite Bitbucket e la loro GUI Git proprietaria, Sourcetree, puoi assolutamente farlo con GitHub e GitLab e i loro strumenti desktop. Puoi anche farlo direttamente dal terminale di comando, ma mi piace automatizzare e semplificare il processo il più possibile, riducendo il rischio di commettere errori stupidi.

Quando hai creato il tuo nuovo repository sulla piattaforma Git di tua scelta, crea una cartella vuota all'interno della cartella del tuo progetto locale (WP2Hugo), ad esempio hugorepo , quindi apri il tuo terminale di comando o lo strumento Git GUI e inizializza il tuo repository Git locale; quindi, collegalo al repository remoto (di solito puoi trovare il comando esatto da utilizzare sul repository remoto appena creato).

Ti consiglio di creare un ramo dev (o stage ) in modo che il tuo ramo principale sia utilizzato rigorosamente per le distribuzioni di produzione. Limiterà anche la generazione di nuove build solo quando avrai terminato con una potenziale serie di modifiche. La creazione di un ramo può essere eseguita localmente o sulla pagina Web remota del repository.

GitHub semplifica la creazione di un ramo facendo clic sul selettore di ramo e digitando un nuovo nome. Su GitLab, devi aprire il menu a discesa "Plus" per accedere all'opzione. Bitbucket richiede di aprire il menu "Plus" a sinistra per aprire il menu a scorrimento e fare clic su "Crea un ramo" nella sezione "Vai al lavoro".

4. Attivazione di Git LFS (opzionale)

Git Large File System è una funzionalità di Git che consente di salvare file di grandi dimensioni in modo più efficiente, come documenti Photoshop, archivi ZIP e, nel nostro caso, immagini. Poiché le immagini possono richiedere il controllo delle versioni ma non sono esattamente codice, ha senso memorizzarle in modo diverso dai normali file di testo. Il modo in cui funziona è archiviare l'immagine su un server remoto e il file nel tuo repository sarà un file di testo che contiene un puntatore a quella risorsa remota.

Purtroppo, non è un'opzione che fai semplicemente clic per abilitare. Devi configurare il tuo repository per attivare LFS e questo richiede un po' di lavoro in locale. Con Git installato, devi installare un'estensione Git-LFS:

 git lfs install

Se, come me, quel comando non ha funzionato per te, prova l'alternativa Homebrew (per macOS o Linux):

 brew install git-lfs

Una volta fatto, dovrai specificare quali file tracciare nel tuo repository. Ospiterò tutte le immagini che ho caricato nella cartella /upload di WordPress in una cartella con lo stesso nome sulla mia configurazione di Hugo, tranne per il fatto che questa cartella sarà all'interno di una cartella /static (che si risolverà nella radice una volta compilata). Decidi la struttura della tua cartella e tieni traccia dei tuoi file all'interno:

 git lfs track "static/uploads/*"

Questo terrà traccia di qualsiasi file all'interno della cartella /static/uploads . Puoi anche usare quanto segue:

 git lfs track "*.jpg"

Questo terrà traccia di tutti i file JPG nel tuo repository. Ad esempio, puoi combinare e abbinare per tracciare solo i JPG in una determinata cartella.

Con questo in atto, puoi inviare i tuoi file di configurazione LFS al tuo repository e inviarli al tuo repository remoto. La prossima volta che esegui il commit in locale di un file che corrisponde alla configurazione di tracciamento LFS, verrà "convertito" in una risorsa LFS. Se lavori su un ramo di sviluppo, unisci questo commit nel tuo ramo principale.

Diamo ora un'occhiata a Netlify.

5. Creazione del sito su Netlify

A questo punto, il tuo repository è impostato, quindi puoi procedere e creare un account su Netlify. Puoi anche accedere con il tuo account GitHub, GitLab o Bitbucket, se lo desideri. Una volta sulla dashboard, fai clic sul pulsante "Nuovo sito da Git" nell'angolo in alto a destra e crea il tuo nuovo sito Netlify.

Nota : per ora puoi lasciare tutte le opzioni ai valori predefiniti.

Seleziona il tuo provider Git: si aprirà una finestra pop-up per autenticarti. Al termine, la finestra si chiuderà e vedrai un elenco di repository su quel provider Git a cui hai accesso. Seleziona il repository appena creato e continua. Ti verranno chieste alcune cose, la maggior parte delle quali puoi semplicemente lasciare per impostazione predefinita poiché tutte le opzioni sono modificabili in seguito.

Per ora, nelle Impostazioni del sito, fai clic su "Cambia il nome del sito" e dai un nome al tuo sito come preferisci: andrò con chris-smashing-hugo-blog . Ora potremo accedere al sito tramite chris-smashing-hugo-blog.netlify.com : una bellissima pagina 404!

6. Preparazione per Netlify Large Media (opzionale)

Se configuri Git LFS e prevedi di utilizzare Netlify, ti consigliamo di seguire questi passaggi. È un po' più contorto ma ne vale sicuramente la pena: ti consentirà di impostare stringhe di query sugli URL delle immagini che verranno automaticamente trasformati.

Supponiamo che tu abbia un link a portrait.jpg che è un'immagine di 900×1600 pixel. Con Netlify Large Media, puoi chiamare il file portrait.jpg?nf_resize=fit&w=420 , che lo ridimensionerà proporzionalmente. Se definisci sia w che h e imposti nf_resize=smartcrop , si ridimensionerà ritagliando per concentrarsi sul punto di interesse dell'immagine (come determinato da un algoritmo di fantasia, noto anche come magia del cervello del robot! ). Trovo che questo sia un ottimo modo per avere miniature come quelle generate da WordPress, senza bisogno di diversi file per un'immagine nel mio repository.

Se questo ti sembra interessante, configuriamolo!

Il primo passo è installare l'interfaccia a riga di comando (CLI) di Netlify tramite npm:

 npm install netlify-cli -g

Se ha funzionato, l'esecuzione del comando netlify dovrebbe generare informazioni sullo strumento.

Dovrai quindi assicurarti di essere nella cartella del repository locale (che ho chiamato "hugorepo" in precedenza) ed eseguire:

 netlify login

Autorizza il token. Successivamente, dovremo installare il plug-in Netlify Large Media. Correre:

 netlify plugins:install netlify-lm-plugin netlify lm:install

Dovrebbe esserci una riga di comando mostrata alla fine del messaggio risultante che devi copiare (che dovrebbe assomigliare a /Users/YOURNAME/.netlify/helper/path.bash.inc su Mac) - eseguilo. Tieni presente che Portachiavi potrebbe chiederti la password di amministratore del tuo computer su macOS.

Il prossimo passo è collegare Netlify:

 netlify link

Puoi fornire il nome del tuo sito qui (ho fornito il nome chris-smashing-hugo-blog che ho dato prima). Con questo in atto, devi solo configurare la funzione Large Media eseguendo quanto segue:

 netlify lm:setup

Invia queste nuove modifiche al tuo repository locale e inviale al ramo di sviluppo remoto. Ho avuto alcuni errori con Sourcetree e Keychain sulla falsariga di git "credential-netlify" is not a git command . Se questo è il tuo caso, prova a spingere manualmente con questi comandi:

 git add -A git commit -m "Set up Netlify Large media" git push

Se ciò non ha funzionato, potrebbe essere necessario installare Netlify Credential Helper. Ecco come farlo con Homebrew:

 brew tap netlify/git-credential-netlify brew install git-credential-netlify

Prova ora a eseguire il commit (con la GUI o il terminale di comando): dovrebbe funzionare!

Nota : se modifichi la tua password Netlify, esegui netlify logout e netlify login nuovo.

Potresti chiedere: "Tutto questo, e non abbiamo ancora nemmeno inizializzato la nostra build Hugo?" Sì, lo so, ci è voluto un po' ma tutti i preparativi per il passaggio sono fatti. Ora possiamo creare il nostro blog Hugo!

7. Configurare Hugo sul tuo computer

Dovrai prima installare Hugo sul tuo computer con una delle opzioni fornite. Userò Homebrew ma gli utenti Windows possono usare Scoop o Chocolatey o scaricare direttamente un pacchetto.

 brew install hugo

Dovrai quindi creare un nuovo sito Hugo ma non gli piacerà configurarlo in una cartella non vuota. Prima opzione: puoi crearlo in una nuova cartella e spostarne il contenuto nella cartella del repository locale:

 hugo new site your_temporary_folder

Seconda opzione: puoi forzarne l'installazione nel tuo repository locale con un flag, assicurati solo di eseguirlo nella cartella giusta:

 hugo new site . --force

Ora hai un sito Hugo, che puoi avviare con questo comando:

 hugo server

Avrai un'anteprima locale su localhost . Purtroppo, non hai contenuti e temi tuoi. Non preoccuparti, lo installeremo molto presto!

Diamo prima un'occhiata al file di configurazione ( config.toml nel mio caso): impostiamo il nome del blog e l'URL di base (questo deve corrispondere all'URL sulla dashboard di Netlify):

 title = "Chris' Smashing Hugo Blog" baseURL = "https://chris-smashing-hugo-blog.netlify.com"

Questo collegamento verrà sovrascritto durante lo sviluppo in locale, quindi non dovresti incorrere in errori 404.

Diamo a Hugo i nostri articoli esportati in formato Markdown. Dovrebbero trovarsi nella /WP2Hugo/blog2md/out dal primo passaggio. Nella cartella Hugo (ovvero la directory del repository locale), accedi alla cartella dei content e crea una sottocartella denominata posts . Inserisci i tuoi file Markdown lì e poi configuriamo un tema.

8. Creazione del tuo tema personalizzato

Per questo passaggio, consiglio di scaricare Saito boilerplate, che è un tema con tutti i parziali necessari per iniziare (e senza stili), un punto di partenza molto utile. Puoi, ovviamente, guardare questa raccolta di temi già pronti per Hugo se vuoi saltare questa parte del processo. Dipende tutto da te!

Dalla cartella del repository locale, clona il tema in themes/saito :

 git submodule add https://github.com/hakuoku/saito-boilerplate.git themes/saito

Puoi rinominare questa cartella come vuoi, ad esempio cool-theme . Dovrai dire alla tua configurazione di Hugo quale tema vuoi usare modificando il tuo file config.toml/yaml/json . Modifica il valore del tema in saito , o cool-theme , o qualunque sia il nome della cartella del tuo tema. La tua anteprima dovrebbe ora mostrare il titolo del tuo blog insieme a una riga di copyright. È un inizio, vero?

Apri il file layout/partials/home.html del tema e modificalo per visualizzare i tuoi contenuti, limitandoti ai primi cinque elementi che sono di tipo posts (all'interno della cartella content/posts/ ), con range , first e where :

 <div class="container"> {{ range first 5 (where .Paginator.Pages "Type" "posts") }} <article class="post post--{{ .Params.class }}"> <h2 class="post__title">{{ .Title }}</h2> <section class="post__content"> {{ .Content }} </section> </article> {{ end }} </div>

Il tuo contenuto è ora visibile, nel modo più semplice. È ora di farlo tuo: tuffiamoci!

Modellazione con Hugo

Puoi prima leggere l'Introduzione al modello di Hugo, se lo desideri, ma cercherò di esaminare alcuni elementi essenziali che ti aiuteranno a comprendere le basi.

Tutte le operazioni in Hugo sono definite all'interno di delimitatori: parentesi graffe doppie (ad es. {{ .Title }} ), che dovrebbero risultare familiari se hai già eseguito un po' di modelli. In caso contrario, pensalo come un modo per eseguire operazioni o iniettare valori in un punto specifico del tuo markup. Per i blocchi, terminano con il tag {{ end }} , per tutte le operazioni a parte gli shortcode.

I temi hanno una cartella di layout che contiene i pezzi del layout. La cartella _default sarà il punto di partenza di Hugo, essendo baseof.html ( hai indovinato! ) la base del tuo layout. Chiamerà ogni componente, chiamato "parziali" (maggiori informazioni su questo nella documentazione di Hugo sul modello parziale), in modo simile a come useresti include in PHP, che potresti aver già visto nel tuo tema WordPress. I parziali possono chiamare altri parziali, ma non renderlo un ciclo infinito.

Puoi chiamare un parziale con {{ partial "file.html" . }} {{ partial "file.html" . }} sintassi. La sezione partial è piuttosto semplice, ma le altre due potrebbero aver bisogno di essere spiegate. Potresti aspettarti di dover scrivere parziali/file.html ma poiché tutti i parziali devono trovarsi nella cartella "parziali", Hugo può trovare quella cartella perfettamente. Naturalmente, puoi creare sottocartelle all'interno della cartella "parziali" se hai bisogno di più organizzazione.

Potresti aver notato un punto vagante: questo è il contesto che stai passando al tuo parziale. Se avessi un menu parziale e un elenco di collegamenti ed etichette, potresti passare quell'elenco al parziale in modo che possa accedere solo a quell'elenco e nient'altro. Parlerò di più di questo punto sfuggente nella prossima sezione.

Il tuo file baseof.html è una shell che chiama tutti i vari parziali necessari per rendere il layout del tuo blog. Dovrebbe avere un HTML minimo e molte parziali:

 <!DOCTYPE html> <html lang="{{ .Site.LanguageCode }}"> <head> <title>{{ block "title" . }}{{ .Site.Title }}{{ end }}</title> {{ partial "head.html" . }} </head> <body> {{ partial "header.html" . }} {{ partial "nav.html" . }} <main> {{ block "main" . }}{{ end }} </main> <aside> {{ partial "sidebar.html" . }} </aside> {{ partial "footer.html" . }} </body> </html>

Il {{ block "main" . }}{{ end }} La riga {{ block "main" . }}{{ end }} è diversa perché è un blocco che viene definito con un modello basato sul contenuto della pagina corrente (homepage, pagina del singolo post, ecc.) con {{ define "main" }} .

Fogli di stile

Nel tuo tema, crea una cartella denominata assets in cui collocheremo una cartella css . Conterrà i nostri file SCSS o un fidato vecchio file CSS. Ora, dovrebbe esserci un file css.html nella cartella partials (che viene chiamata da head.html ). Per convertire Sass/SCSS in CSS e minimizzare il foglio di stile, useremmo questa serie di funzioni (usando la sintassi di Hugo Pipes invece di avvolgere le funzioni l'una attorno all'altra):

 {{ $style := resources.Get "css/style.scss" | toCSS | minify | fingerprint }}

Come bonus, dal momento che ho faticato a trovare una risposta diretta, se vuoi usare Autoprefixer, Hugo implementa anche PostCSS. Puoi aggiungere una funzione pipe aggiuntiva tra toCSS e minify sulla prima riga, in questo modo:

 {{ $style := resources.Get "css/style.scss" | toCSS | postCSS | minify | fingerprint }}

Crea un file "postcss.config.js" nella radice del tuo blog Hugo e passa le opzioni, come ad esempio:

 module.exports = { plugins: { autoprefixer: { browsers: [ "> 1%", "last 2 versions" ] } }, }

E presto! Dal Sass al CSS prefissato e minimizzato. La funzione pipe "impronta digitale" serve per assicurarsi che il nome del file sia univoco, come style.c66e6096bdc14c2d3a737cff95b85ad89c99b9d1.min.css . Se modifichi il foglio di stile, l'impronta digitale cambia, quindi il nome del file è diverso e, quindi, ottieni una soluzione efficace per busting della cache.

9. Note sulla sintassi di Hugo

Voglio assicurarmi che tu capisca "il punto", che è il modo in cui Hugo valuta le variabili (o, nelle mie stesse parole, fornisce un riferimento contestuale) che utilizzerai nei tuoi modelli.

Il punto e l'ambito

Il punto è come una variabile di primo livello che puoi utilizzare in qualsiasi modello o shortcode, ma il suo valore è nell'ambito del suo contesto. Il valore del punto in un modello di primo livello come baseof.html è diverso dal valore all'interno di blocchi di loop o with blocchi.

Diciamo che questo è nel nostro modello nel nostro parziale head.html :

 {{ with .Site.Title }} {{ fine }}

Anche se lo stiamo eseguendo nell'ambito principale, il valore del punto cambia in base al contesto, che in questo caso è .Site.Title . Quindi, per stampare il valore, devi solo scrivere . invece di digitare nuovamente il nome della variabile. Questo all'inizio mi ha confuso, ma ti ci abitui molto rapidamente e aiuta a ridurre la ridondanza poiché dai un nome alla variabile solo una volta. Se qualcosa non funziona, di solito è perché stai cercando di chiamare una variabile di primo livello all'interno di un blocco con ambito.

Quindi, come si utilizza l'ambito di livello superiore all'interno di un blocco con ambito? Bene, supponiamo che tu voglia controllare un valore ma usarne un altro. Puoi usare $ che sarà sempre l'ambito di primo livello:

 {{ with .Site.Params.InfoEnglish }}{{ $.Site.Params.DescriptionEnglish }}{{ end }}

All'interno della nostra condizione, l'ambito è .Site.Params.InfoEnglish ma possiamo comunque accedere ai valori al di fuori di esso con $ , dove l'utilizzo intuitivo di .Site.Params.DescriptionEnglish non funzionerebbe perché tenterebbe di risolversi in .Site.Params.InfoEnglish.Site.Params.DescriptionEnglish , generando un errore.

Variabili personalizzate

È possibile assegnare variabili utilizzando la seguente sintassi:

 {{ $customvar := "custom value" }}

Il nome della variabile deve iniziare con $ e l'operatore di assegnazione deve essere := se è la prima volta che viene assegnata, = altrimenti in questo modo:

 {{ $customvar = "updated value" }}

Il problema che potresti incontrare è che questo non trasparerà dall'ambito, il che mi porta al punto successivo.

Graffio

La funzionalità Scratch consente di assegnare valori disponibili in tutti i contesti. Supponiamo di avere un elenco di film in un file movies.json :

 [ { "name": "The Room", "rating": 4 }, { "name": "Back to the Future", "rating": 10 }, { "name": "The Artist", "rating": 7 } ]

Ora, vuoi scorrere il contenuto del file e archiviare il tuo preferito per usarlo in seguito. È qui che entra in gioco Scratch:

 {{ .Scratch.Set "favouriteMovie" "None" }}{{ /* Optional, just to get you to see the difference syntax based on the scope */ }} {{ range .Site.Data.movies }} {{ if ge .rating 10 }} {{ /* We must use .Scratch prefixed with a $, because the scope is .Site.Data.movies, at the current index of the loop */ }} {{ $.Scratch.Set "favouriteMovie" .name }} {{ end }} {{ end }} [...] My favourite movie is {{ .Scratch.Get "favouriteMovie" }} <!-- Expected output => My favourite movie is Back to the Future -->

Con Scratch, possiamo estrarre un valore dall'interno del ciclo e usarlo ovunque. Man mano che il tuo tema diventa sempre più complesso, probabilmente ti ritroverai a cercare Scratch.

Nota : questo è solo un esempio in quanto questo ciclo può essere ottimizzato per produrre questo risultato senza Scratch, ma questo dovrebbe darti una migliore comprensione di come funziona.

Condizionali

La sintassi per i condizionali è leggermente diversa da quella che ti aspetteresti, da una prospettiva JavaScript o PHP. Esistono, in sostanza, funzioni che accettano due argomenti (parentesi facoltativa se si chiamano direttamente i valori):

 {{ if eq .Site.LanguageCode "en-us" }}Welcome!{{ end }}

Esistono diverse di queste funzioni:

• eq verifica l'uguaglianza
• ne controlla la disuguaglianza
• gt controlla maggiore di
• ge se è maggiore o uguale a
• lt meno di
• le controlla minore o uguale a

Nota : puoi imparare tutto sulle funzioni offerte da Hugo nella Guida rapida alle funzioni di Hugo.

Spazio bianco

Se sei schizzinoso sull'output come me, potresti notare alcune righe vuote indesiderate. Questo perché Hugo analizzerà il tuo markup così com'è, lasciando righe vuote attorno alle condizioni che non sono state soddisfatte, ad esempio.

Diciamo di avere questo ipotetico parziale:

 {{ if eq .Site.LanguageCode "en-us" }} <p>Welcome to my blog!</p> {{ end }} <img src="/uploads/portrait.jpg" alt="Blog Author">

Se il codice della lingua del sito non è en-us , questo sarà l'output HTML (notare le tre righe vuote prima del tag immagine):

 <img src="/uploads/portrait.jpg" alt="Blog Author">

Hugo fornisce una sintassi per risolvere questo problema con un trattino accanto alle parentesi graffe all'interno del delimitatore. {{- taglierà lo spazio bianco prima delle parentesi graffe e -}} taglierà lo spazio bianco dopo le parentesi graffe. Puoi utilizzare uno o entrambi contemporaneamente, ma assicurati solo che ci sia uno spazio tra il trattino e l'operazione all'interno del delimitatore.

Pertanto, se il tuo modello contiene quanto segue:

 {{- if eq .Site.LanguageCode "en-us" -}} <p>Welcome to my blog!</p> {{- end -}} <img src="/uploads/portrait.jpg" alt="Blog Author">

...quindi il markup risulterà in questo (senza righe vuote):

 <img src="/uploads/portrait.jpg" alt="Blog Author">

Questo può essere utile per altre situazioni come elementi con display: inline-block che non dovrebbe avere spazi bianchi tra di loro. Al contrario, se vuoi assicurarti che ogni elemento sia su una propria riga nel markup (ad esempio in un ciclo {{ range }} ), dovrai posizionare con cura i trattini per evitare il taglio "avido" degli spazi bianchi.

L'esempio precedente genererebbe quanto segue se il codice della lingua del sito corrisponde a " en-us " (non ci sono più interruzioni di riga tra i tag p e img ):

 <p>Welcome to my blog!</p><img src="/uploads/portrait.jpg" alt="Blog Author">

10. Contenuto e dati

I tuoi contenuti vengono archiviati come file Markdown, ma puoi anche utilizzare HTML. Hugo lo renderà correttamente durante la creazione del tuo sito.

La tua home page chiamerà il layout _default/list.html , che potrebbe assomigliare a questo:

 {{ define "main" }} {{ partial "list.html" . }} {{ end }}

Il blocco principale chiama il parziale list.html con il contesto di . , alias il livello più alto. Il parziale list.html potrebbe essere simile a questo:

 {{ define "main" }} <ol class="articles"> {{ range .Paginator.Pages }} <li> <article> <a href="{{ .URL }}"> <h2>{{ .Title }}</h2> <img src="{{ .Params.featuredimage }}" alt=""> <time datetime="{{ .Date.Format "2006-01-02" }}"> {{ .Date.Format "January 2 2006" }} </time> </a> </article> </li> {{ end }} </ol> {{ partial "pagination.html" . }} {{ end }}

Ora abbiamo un elenco di base dei nostri articoli, che puoi modellare come desideri! Il numero di articoli per pagina è definito nel file di configurazione, con paginate = 5 (in TOML).

Potresti essere completamente confuso come lo ero io per la formattazione della data in Hugo. Ogni volta che l'unità è mappata su un numero (primo mese, secondo giorno, terza ora, ecc.) ha avuto molto più senso per me una volta che ho visto la spiegazione visiva di seguito fornita dalla documentazione in lingua Go - il che è un po' strano, ma anche un po' intelligente!

 Jan 2 15:04:05 2006 MST => 1 2 3 4 5 6 -7

Ora tutto ciò che resta da fare è visualizzare il tuo post su un'unica pagina. Puoi modificare il post.html parziale per personalizzare il layout del tuo articolo:

 <article> <header> <h1>{{ .Title }}</h1> <p> Posted on <time datetime="{{ .Date.Format "2006-01-02" }}">{{ .Date.Format "2006. 1. 2" }}</time> </p> </header> <section> {{ .Content }} </section> </article>

Ed è così che visualizzi i tuoi contenuti!

Se desideri personalizzare l'URL, aggiorna il tuo file di configurazione aggiungendo un'opzione [permalinks] (TOML), che in questo caso farà apparire gli URL come my-blog.com/post-slug/ :

 [permalinks] posts = ":filename/"

Se vuoi generare un feed RSS dei tuoi contenuti (perché RSS è fantastico), aggiungi quanto segue nel file di configurazione del tuo sito (il modello predefinito di Saito visualizzerà i tag appropriati in head.html se vengono rilevate queste opzioni):

 rssLimit = 10 [outputFormats] [outputFormats.RSS] mediatype = "application/rss" baseName = "feed"

Ma cosa succede se avessi una sorta di contenuto al di fuori di un post? È qui che entrano in gioco i modelli di dati: puoi creare file JSON ed estrarne i dati per creare il tuo menu o un elemento nella barra laterale. YAML e TOML sono anche opzioni ma meno leggibili con dati complessi (es. oggetti annidati). Ovviamente potresti impostarlo nel file di configurazione del tuo sito, ma per me è un po' meno facile da navigare e meno indulgente.

Creiamo un elenco di "siti interessanti" che potresti voler mostrare nella barra laterale, con un collegamento e un'etichetta per ogni sito come array in JSON:

 { "coolsites": [ { "link": "https://smashingmagazine.com", "label": "Smashing Magazine" }, { "link": "https://gohugo.io/", "label": "Hugo" }, { "link": "https://netlify.com", "label": "Netlify" } ] }

Puoi salvare questo file nella radice del tuo repository, o nella radice del tuo tema, all'interno di una cartella di data , come /data/coolsites.json . Quindi, nel tuo sidebar.html parziale, puoi scorrere su di esso con l' range usando .Site.Data.coolsites :

 <h3>Cool Sites:</h3> <ul> {{ range .Site.Data.coolsites.coolsites }} <li><a href="{{ .link }}">{{ .label }}</a></li> {{ end }} </ul>

Questo è molto utile per qualsiasi tipo di dato personalizzato su cui desideri eseguire l'iterazione. L'ho usato per creare un elenco di Google Fonts per il mio tema, in quali categorie possono trovarsi i post, autori (con biografia, avatar e link alla home page), quali menu mostrare e in quale ordine. Puoi davvero fare molto con questo, ed è piuttosto semplice.

Un ultimo pensiero sui dati e simili: tutto ciò che metti nella tua cartella Hugo /static sarà disponibile nella radice ( / ) nella build live. Lo stesso vale per la cartella del tema.

11. Distribuzione su Netlify

Quindi hai finito, o forse vuoi solo vedere che tipo di magia opera Netlify? Mi sembra buono, purché il tuo server Hugo locale non restituisca un errore.

Conferma le modifiche e inviale al tuo ramo di sviluppo remoto ( dev ). Vai su Netlify e accedi alle impostazioni del tuo sito. Vedrai un'opzione per "Crea e distribuisci". Avremo bisogno di cambiare un paio di cose qui.

1. Innanzitutto, nella sezione "Impostazioni build", assicurati che "Build command" sia impostato su hugo e che "Publish directory" sia impostato su public (l'impostazione predefinita che si consiglia di mantenere nel file di configurazione di Hugo);
2. Quindi, nella sezione "Distribuisci contesti", imposta "Ramo di produzione" sul tuo ramo principale nel tuo repository. Suggerisco anche di impostare "Distribuisce il ramo" su "Distribuisci solo il ramo di produzione";
3. Infine, nella sezione “Variabili d'ambiente”, modifica le variabili e clicca su “Nuova variabile”. Imposteremo l'ambiente Hugo su 0.53 con la seguente coppia: set key su HUGO_VERSION e valore su 0.53 .

Ora vai al tuo repository remoto e unisci il tuo ramo di sviluppo nel tuo ramo principale: questo sarà l'hook che distribuirà il tuo blog aggiornato (questo può essere personalizzato ma l'impostazione predefinita è ragionevole per me).

Tornando alla dashboard di Netlify, le "Distribuzioni di produzione" del tuo sito dovrebbero avere qualche nuova attività. Se tutto è andato per il verso giusto, questo dovrebbe essere elaborato e risolto in un'etichetta "Pubblicato". Facendo clic sull'elemento di distribuzione si aprirà una panoramica con un registro delle operazioni. In alto, vedrai "Anteprima distribuzione". Vai avanti, fai clic su di esso: te lo meriti. È vivo!

12. Impostazione di un dominio personalizzato

Avere l'URL come my-super-site.netlify.com non è di tuo gusto e possiedi già my-super-site.com ? Capisco. Cambiamo quello!

Vai al registrar del tuo dominio e vai alle impostazioni DNS del tuo dominio. Qui, dovrai creare una nuova voce: puoi impostare un record ALIAS/CNAME che punta a my-super-site.netlify.com o impostare un record A che punta il tuo dominio al sistema di bilanciamento del carico di Netlify, che è 104.198.14.52 al momento della scrittura.

Puoi trovare le ultime informazioni sulla documentazione di Netlify sui domini personalizzati. L'IP del sistema di bilanciamento del carico sarà nella sezione delle impostazioni DNS, in "Configurazione DNS manuale per i domini personalizzati root e www".

Al termine, vai alla dashboard del tuo sito su Netlify e fai clic su "Impostazioni dominio", dove vedrai "Aggiungi dominio personalizzato". Inserisci il tuo nome di dominio per verificarlo.

Puoi anche gestire i tuoi domini tramite la dashboard nella scheda Domini. L'interfaccia sembra meno confusa in questa pagina, ma forse aiuterà a dare più senso alle tue impostazioni DNS come ha fatto per me.

Nota : Netlify può anche gestire tutto per te se desideri acquistare un dominio tramite loro. È più facile ma è un costo aggiuntivo.

Dopo aver impostato il tuo dominio personalizzato, in "Impostazioni dominio", scorri verso il basso fino alla sezione "HTTPS" e abilita il certificato SSL/TLS. Potrebbero volerci alcuni minuti ma ti garantirà un certificato gratuito: il tuo dominio ora funziona su HTTPS.

13. Modifica dei contenuti su Netlify CMS

Se vuoi modificare i tuoi articoli, caricare immagini e modificare le impostazioni del tuo blog come faresti sull'interfaccia back-end di WordPress, puoi utilizzare Netlify CMS che ha un tutorial abbastanza buono disponibile. È un singolo file che gestirà tutto per te (ed è indipendente dal generatore: funzionerà con Jekyll, Eleventy e così via).

Devi solo caricare due file in una cartella:

• il CMS (un unico file HTML);
• un file di configurazione (un file YAML).

Quest'ultimo manterrà tutte le impostazioni del tuo particolare sito.

Vai alla cartella /static della tua radice Hugo e crea una nuova cartella a cui accederai tramite my-super-site.com/FOLDER_NAME (chiamerò il mio admin ). All'interno di questa cartella admin , crea un file index.html copiando il markup fornito da Netlify CMS:

 <!doctype html> <html> <head> <meta charset="utf-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>Content Manager</title> </head> <body> <!-- Include the script that builds the page and powers Netlify CMS --> <script src="https://unpkg.com/netlify-cms@^2.0.0/dist/netlify-cms.js"></script> </body> </html>

L'altro file che dovrai creare è il file di configurazione: config.yml . Ti consentirà di definire le impostazioni del tuo sito (nome, URL, ecc.) in modo da poter impostare ciò che dovrebbe contenere la prima pagina dei tuoi post e come dovrebbero essere modificabili i tuoi file di dati (se presenti). È un po' più complesso da configurare, ma ciò non significa che non sia facile.

Se stai usando GitHub o GitLab, avvia il tuo file config.yml con:

 backend: name: git-gateway branch: dev # Branch to update (optional; defaults to master)

Se stai usando Bitbucket, è un po' diverso:

 backend: name: bitbucket repo: your-username/your-hugorepo branch: dev # Branch to update (optional; defaults to master)

Quindi, per i nostri caricamenti, dovremo dire al CMS dove archiviarli:

 media_folder: "static/images/uploads" # Media files will be stored in the repo under static/images/uploads public_folder: "/images/uploads" # The src attribute for uploaded media will begin with /images/uploads

Quando crei un nuovo post, il CMS genererà lo slug per il nome del file che puoi personalizzare con tre opzioni:

slug: encoding: "ascii" # You can also use "unicode" for non-Latin clean_accents: true # Removes diacritics from characters like e or a sanitize_replacement: "-" # Replace unsafe characters with this string

Infine, dovrai definire come sono strutturati i dati nei tuoi post. Definirò anche come è strutturato il file di dati coolsites , nel caso in cui volessi aggiungere un altro sito all'elenco. Questi sono impostati con l'oggetto delle collections che sarà sicuramente il più dettagliato, insieme a una bella manciata di opzioni di cui puoi leggere di più qui.

 collections: - name: "articles" # Used in routes, eg, /admin/collections/blog label: "Articles" # Used in the Netlify CMS user interface folder: "content/posts" # The path to the folder where the posts are stored, usually content/posts for Hugo create: true # Allow users to create new documents in this collection slug: "{{slug}}" # Filename template, eg, post-title.md fields: # The fields for each document, usually in front matter - {label: "Title", name: "title", widget: "string", required: true} - {label: "Draft", name: "draft", widget: "boolean", default: true } - {label: "Type", name: "type", widget: "hidden", default: "post" } - {label: "Publish Date", name: "date", widget: "date", format: "YYYY-MM-DD"} - {label: "Featured Image", name: "featuredimage", widget: "image"} - {label: "Author", name: "author", widget: "string"} - {label: "Body", name: "body", widget: "markdown"} - name: 'coolsites' label: 'Cool Sites' file: 'data/coolsites.json' description: 'Website to check out' fields: - name: coolsites label: Sites label_singular: 'Site' widget: list fields: - { label: 'Site URL', name: 'link', widget: 'string', hint: 'https://…' } - { label: 'Site Name', name: 'label', widget: 'string' }

Nota : puoi leggere di più su come configurare i singoli campi nella documentazione di Netlify CMS Widgets che esamina ogni tipo di widget e come usarli, particolarmente utile per i formati di data.

Autenticazione

L'ultima cosa che dobbiamo fare è assicurarci che solo gli utenti autorizzati possano accedere al backend! Usare l'autenticazione del tuo provider Git è un modo semplice per farlo.

Vai al tuo sito Netlify e fai clic sulla scheda "Impostazioni". Quindi vai su "Controllo accessi" che è l'ultimo collegamento nel menu sul lato sinistro. Qui puoi configurare OAuth per l'esecuzione tramite GitHub, GitLab o Bitbucket fornendo una chiave e un valore segreto definiti per il tuo account utente (non nel repository). Ti consigliamo di utilizzare lo stesso provider Git su cui è salvato il tuo repository.

GitHub

Vai alla tua pagina "Impostazioni" su GitHub (fai clic sul tuo avatar per visualizzare il menu) e accedi a "Impostazioni sviluppatore". Fare clic su "Registra una nuova applicazione" e fornire i valori richiesti:

• un nome, come “Netlify CMS per il mio super blog”;
• un URL della home page, il link al tuo sito Netlify;
• una descrizione, se ne hai voglia;
• l'URL di richiamata dell'applicazione, che deve essere " https://api.netlify.com/auth/done ".

Salva e vedrai il tuo ID cliente e Segreto cliente. Fornirli al controllo di accesso di Netlify.

GitLab

Fai clic sul tuo avatar per accedere alla pagina Impostazioni e fai clic su "Applicazioni" nel menu "Impostazioni utente" a sinistra. Verrà visualizzato un modulo per aggiungere una nuova applicazione. Fornire le seguenti informazioni:

• un nome, come “Netlify CMS per il mio super blog”;
• un URI di reindirizzamento, che deve essere “ https://api.netlify.com/auth/done ”;
• gli ambiti da verificare sono:
  • api
  • read_user
  • read_repository
  • write_repository
  • read_registry

Il salvataggio dell'applicazione ti darà l'ID dell'applicazione e il segreto, che ora puoi inserire nel controllo di accesso di Netlify.

Bitbucket

Vai alle impostazioni del tuo account utente (fai clic sul tuo avatar, quindi su "Impostazioni Bitbucket"). In "Gestione accessi", fai clic su "OAth". Nella sezione "Consumatori OAuth", fai clic su "Aggiungi consumatore". Puoi lasciare la maggior parte delle cose ai valori predefiniti tranne questi:

• un nome, come “Netlify CMS per il mio super blog”;
• un URL di richiamata, che deve essere " https://api.netlify.com/auth/done ";
• i permessi da verificare sono:
  • Account: e-mail, lettura, scrittura
  • Repository: lettura, scrittura, amministrazione
  • Richieste pull: leggi, scrivi
  • Webhook: leggi e scrivi

Dopo il salvataggio, puoi accedere alla tua chiave e al tuo segreto, che puoi quindi fornire di nuovo sul controllo di accesso di Netlify.

Dopo aver fornito i token, vai su Netlify e trova le Impostazioni del sito. Vai su "Identità" e abilita la funzione. Ora puoi aggiungere un Provider Esterno: seleziona il tuo provider Git e clicca su “Abilita”.

Se hai bisogno di ulteriori dettagli, Netlify CMS ha una guida all'autenticazione che puoi leggere.

Ora puoi accedere al backend del tuo sito Netlify e modificare i contenuti. Ogni modifica è un commit sul tuo repository, nel ramo specificato nel tuo file di configurazione. Se hai mantenuto il tuo ramo main come destinazione per Netlify CMS, ogni volta che salvi, verrà eseguita una nuova build. Più conveniente, ma non così pulito con gli "stati intermedi".

Averlo salvato su un ramo dev ti consente di avere un controllo più preciso su quando vuoi eseguire una nuova build. Questo è particolarmente importante se il tuo blog ha molti contenuti e richiede un tempo di costruzione più lungo. In entrambi i casi funzionerà; è solo una questione di come vuoi gestire il tuo blog .

Inoltre, tieni presente che Git LFS è qualcosa che hai installato localmente, quindi le immagini caricate tramite Netlify CMS saranno "normali". Se estrai il tuo ramo remoto localmente, le immagini dovrebbero essere convertite in LFS, che puoi quindi eseguire il commit e il push nel tuo ramo remoto. Inoltre, Netlify CMS attualmente non supporta LFS, quindi l'immagine non verrà visualizzata nel CMS, ma verrà visualizzata nella build finale.

Letture consigliate : Generatori di siti statici recensiti: Jekyll, Middleman, Roots, Hugo

Conclusione

Che giro! In questo tutorial, hai imparato come esportare il tuo post WordPress in file Markdown, creare un nuovo repository, configurare Git LFS, ospitare un sito su Netlify, generare un sito Hugo, creare il tuo tema e modificare il contenuto con Netlify CMS . Non male!

Qual è il prossimo? Bene, potresti sperimentare con la tua configurazione di Hugo e leggere di più sui vari strumenti offerti da Hugo: ce ne sono molti che non ho trattato per brevità.

Esplorare! Divertiti! Blog!

Ulteriori risorse

• Documentazione Hugo
  • Installazione
  • Avvio rapido
  • Configurazione
  • Modellazione
  • Tassonomie
  • codici brevi
  • Hugo su Netlify
• Documentazione Netlify
  • Domini personalizzati
  • DNS gestito
  • netlify.toml Distribuire gli script
• Documentazione Netlify CMS
  • Widget
• Git LFS