Shortcode e appunti vari per ox-hugo

Visto che in questo periodo sto studiando come usare al meglio (ox)Hugo ed Emacs per la gestione del blog, ecco un articolo che in realtà è più un promemoria personale su come gestire i contenuti. Di seguito ho raccolto una carrellata di casistiche, dalle più comuni alle più particolari che mi sono trovato ad affrontare fino ad ora.

Introduzione (summary) degli articoli

Normalmente l’introduzione degli articoli, detta anche “summary”, viene generata automaticamente a partire dal testo ma io preferisco definirla sempre manualmente in modo che sia più precisa e personalizzata.

Pertanto si può usare il parametro summary.

N.B: Da notare come sia possibile inserire anche codice markdown all’interno del summary, tale codice verrà convertito in HTML da Hugo.

File .org unico per il blog (default)

Nella sezione :PROPERTIES: del post si inserisce il testo dell’introduzione nel seguente modo:

:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :summary "Test da usare come introduzione"

File .org separato per ogni post

In alternativa, se si usa un file .org separato per ciascun articolo si inserisce il seguente codice nella intestazione del file:

#+HUGO_CUSTOM_FRONT_MATTER: :summary "Esempio di testo per introduzione"

Definire la prima parte del testo per l’introduzione

Se invece si vuole usare la prima parte del testo come “summary”, allora si puòinserire il seguente codice per indicare che il testo precedente fa parte del summary.

#+hugo: more

Attenzione: in questo modo il markup verrà mostrato, quindi a livello di impaginazione sarà necessario tenere in considerazione tale comportamento.

Inserire le citazioni

Per inserire una citazione si usa il codice #+begin_quote. Al suo interno si può mettere il nome della persona citata usando il tag <cite>. Infine per mandare a capo con un “line break” si usa \\.

Ecco un esempio di codice:

#+begin_quote
Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor. Aenean massa. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. \\
<cite>Lorem Ipsum</cite>
#+end_quote

Ed ecco il risultato finale:

Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aenean commodo ligula eget dolor. Aenean massa. Cum sociis natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus.
<cite>Lorem Ipsum</cite>

Collegamenti di testo con attributo title

Normalmente i link si possono inserire con la sintassi standard Org, se però vogliamo aggiungere l’attributo title allora questo va scritto nella riga che precede il link usando il codice: #+attr_html: :title Valore. Ecco qui di seguito un esempio:

#+attr_html: :title Title
[[https://www.example.com][Link con attributo title]]

Ed ecco il risultato:

Attenzione: questo sistema funziona con link su singole righe

Inserimento shortcode con Hugo 0.60+

A partire da Hugo 0.60 non si possono più mettere gli shortcode usando la vecchia sintassi con {{ seguito da %, ma va messo il < (e di conseguenza > al posto del % finale).

Ok, ho riletto la frase ed effettivamente non è il massimo della chiarezza, ma se ti trovi con il problema davanti agli occhi questa spiegazione diventa chiarissima. Spero.

Aggiornamento del 09/11/2022: ho scoperto che la precedente sintassi non funziona più. Ora se si deve inserire uno shortcode ci sono diverse alternative. In particolare io sto usando la seguente modalità:

@@hugo:{{<nome-shortcode>}}@@

Che in markdown diventa:

{{<nome-shortcode>}}

Per maggiori informazioni consiglio di guardare la documentazione ufficiale sugli Shortcode che ha numerosi esempi.

Frammenti o blocchi di codice

Se si scrive del testo all’interno di una coppia di caratteri ~ oppure =, questo testo verrà renderizzato con il un tag HTML <code>. È molto utile quando si vuole inserire qualche frammento di codice.

Se invece si vuole inserire un blocco di codice sorgente in un articolo basta indicare il linguaggio da usare e poi eventuali altri parametri, ad esempio se mostrare il numero di linea o quali righe evidenziare.

In questo esempio è stato attivato il syntax highlight per php5 e sono evidenziate le righe 1, 3 e 4:

#+begin_src php5 :hl_lines 1,3-4

Ecco il risultato finale:

<?php
// Il codice viene evidenziato:
echo 'Stringa';
/* Inoltre possiamo mettere anche
   dei commenti su più righe. */
if ( $variable == true ){
  echo 'Altro test per istruzione if';
}
echo 'Test finale'; # Commenti anche così

Attenzione, se si vuole mostrare il codice di uno shortcode, compreso tra {{< e >}}, bisogna ricordarsi di aggiungere /* e */ appena dopo l’apertura dello shortcode e appena prima della chiusura. Quindi il codice, all’interno di un blocco #BEGIN_SRC sarà una cosa del tipo: {{</* e */>}}.

Inserire elenchi di termini e definizioni

Per inserire una lista di termini e definizioni usando la sintassi HTML5 che sfrutta i tag dl, dt e dd, basta creare una lista normalissima con due “due punti” (::) per separare ogni termine dalla propria definizione.

Ecco un esempio:

- termine uno :: definizione uno
- termine due :: definizione due
- termine tre :: definizione tre

Ed ecco il risultato:

termine uno

definizione uno

termine due

definizione due

termine tre

definizione tre

Gestione tag mark (evidenziatore)

Visto che org-mode non prevede la gestione di un tag equivalente al tag <mark> di HTML5, allora quest’ultimo lo possiamo inserire direttamente nel codice org a patto che sia attiva l’opzione per gestire il markup HTML incluso nel contenuto, ovvero aggiungendo la seguente configurazione nel file config.toml di Hugo:

[markup.goldmark.renderer]
  unsafe = true

Il testo <mark>evidenziato</mark> lo si inserisce usando la seguente sintassi:

<mark>testo</mark>

Shortcut per Emacs per esportare il post corrente

Con il cursore in qualunque punto di un post, la scorciatoia C-c C-e H H permette di esportare il post corrente sotto forma di file Markdown senza dover esportare anche tutti gli altri file.