Un workflow con Emacs, realizzare contenuti web attraverso la sintassi org-mode

Sun, Jan 3, 2021 5-minute read

Workflow basato su Emacs.

Emacs, odiato da molti ma amato dal sottoscitto, in un altro articolo descrivero’ come usare Emacs anche per leggere la posta elettronica…

Premessa.

La configurazione che propongo non e’ certo per tutti. Mi rivolgo agli addetti ai lavori (programmatori, amministratori di sistema) che operano prevalentemente in ambiente Linux/Unix ma soprattutto sono utenti (Desktop o Laptop) Linux a loro volta. Perche’? Non e’ mia intenzione convincere nessuno, i miei perche’ sono legati alla user experience personale. Trovo che Emacs sia uno strumento fantastico, divertente e interamente personalizzabile anzi addirittura extreme customizable. In questo caso specifico e’ addirittura perfetto, vediamo come.

Il problema.

In questo spiegavo come ho realizzato il sito web che utilizzo come personale “blocco note”. Una soluzione perfetta per le mie esigenze dicevo, ma con un problema, quello di adoperare due linguaggi di video scrittura, org-mode per i miei appunti e markdown per la pubblicazione delle pagine web. Le funzionalita’ di esportazione da orgfile a markdown era imprecisa, ero costretto a metterci sempre mano, tagliare e incollare parti, eliminare porzioni di html dal file markdown. Insomma una situazione che mi disturbava e non molto ottimizzata. Avevo bisogno di avere un’unica fonte dalla quale esportare il contenuto da mettere sul web senza ulteriori passaggi di elaborazione, dagli appunti al web due click.

Iniziare, cosa serve e cosa daro’ per scontato.

Partiamo dalla fine, non scrivero’ su come installare Emacs, come installare Doom Emacs, che cosa sia Org-Mode e cosa sia Markdown, troverete i link in basso per provare a capire ma anche dei miei appunti in altri post. Quindi daro’ per scontato che questi elementi siamo almeno conosciuti anche se non abitualmente utilizzati.

Il punto di partenza sara’ quindi un contesto Linux (ArchLinux per me), Emacs con la distribuzione Doom Emacs installata e funzionante. A bordo del vostro ambiente di sviluppo avrete anche Hugo, ed un semplice sito web da poter consultare localmente sulla vostra macchina, ovvero aprendo un browser web e andando sulll’URL http://localhost:1313 potrete visualizzare le pagine. Questo e’ solo per poter verificare che le funzionalita’ di esportazione vengano correttamente interpretate da Hugo.

Prima fase, abilitare il package ox-hugo.

ox-hugo e’ il package che aggiungeremo a Emacs (e’ distribuito da Melpa) vi permette di risolvere il problema di cui prima. Dobbiamo modificare la configurazione di Doom Emacs per scaricare e attivare il package. Editeremo e modificheremo il file init.el che sara’ nella directory ~/.doom.d

(doom! :input
    [..]
        :lang
        (org +hugo)

Di fatto andremo a modificare o aggiungere la riga (org +hugo) nella sezione :lang del file di configurazione di Doom Emacs. Chiuso e salvato il file passeremo alla vera e propria installazione.

cd ~/.emacs.d
./bin/doom sync -u

Il tempo di scaricare e compilare il package e riavviando Emacs sarete gia’ operativi.

Secondo fase, editare un file .org

Le sintassi base con org-mode non cambieranno ma si arricchiranno per renderlo esportabile per Hugo. Dovremo quindi adottare alcune nuove keyword. Una pagine per Hugo deve contenere in testa alcune righe come nel seguente esempio:

+++
title = "Il Mio post"
description = "Come scrivere un post"
author = "Il tuo amichevole spiderman di quartiere"
type = "page"
date = "2020-03-18"
+++

Allo stesso modo nel vostro file .org questa parte dovra’ essere sostituita con (vedi bullet 1 nell’immagine):

#+title: Il Mio post
#+hugo_base_dir: ~/repo/ktxoblabcom/
#+hugo_section: post/2021
#+date: <2021-01-03 Sun>
#+author: {ktx}
#+language: it
#+type: page

Dovrete inserire due keyword che saranno necessarie, hugo_base_dir e hugo_section. La prima indica alla funzione di esportazione dove salvare il file .md, la seconda in quale sezione del sito web. Per la data potrete sempre utilizzare le funzioni calendar di org-mode (C-c .) che servira’ ad Hugo come data di riferimento. Tutto cio’ sempre in testa al file.

Nella parte testuale (vedi bullet 2 nell’immagine) deve essere inserita, ad esempio dopo il primo paragrafo, alcune keyword che forniscono importanti informazioni in fase di export, la descrizione, il nome del file e il peso (es: auto). La tabella che trovate dopo vi offre la comparazione tra come scrivere in org-mode le keyword che poi vengono interpretate da Hugo server.

:properties:
:export_description: Qui descivo la pagina
:export_file_name: il-mio-nome-file-del-post
:export_hugo_weight: auto
:end:
Org entry Hugo Interpreter
#+title: foo title = “foo”
#+date: 2017-07-24 date = 2017-07-24
#+hugo_publishdate: 2018-01-26 publishDate = 2018-01-26
#+hugo_expirydate: 2999-01-01 expiryDate = 2999-01-01
#+hugo_auto_set_lastmod: t lastmod =
#+hugo_tags: toto zulu tags = [“toto”, “zulu”]
#+hugo_categories: x y categories = [“x”, “y”]
#+hugo_draft: true draft = true
#+hugo_draft: false draft = false
#+hugo_weight: 123 weight = 123
#+hugo_weight: :tags 123 tags_weight = 123
#+hugo_weight: :categories 123 categories_weight = 123
#+hugo_menu: :menu foo :weight 123 weight = 123 (in [menu.foo])

Figura 1: Emacs Screenshot

Figura 1: Emacs Screenshot

Esportazione.

Ebbene avrete ottenuto il vostro testo, per verificarlo attraverso il framework Hugo, localmente sulla macchina (http://localhost:1313), dovrete eseguire l’esportazione. Se non avete altre personalizzazioni, l’esportazione avviene attraverso il rischiamo del menu di export tramite la sequneza `C-c C-e` (Crtl+c Ctrl+e). Successivamente potrete indicare di esportare in markdown con H-h (Markdown compatibil con Hugo). Il file .md sara’ esportato seguendo il percordo che indicherete alla variabile hugo_base_dir.

Conclusioni.

Ho dato per scontate molte informazioni. Utilizzare una distribuzione Emacs come Doom Emacs e’ un’assoluta facilitazione anche per un vecchio come me. Fornisce la correzione della sintassi e dello spell checking on-the-fly, il suggerimento delle funzioni (snippet) come tutte le features che i moderni IDE forniscono. A Doom Emacs non manca nulla. Di fatto utilizzerete per scrivere sempre la sintassi Org-Mode dimenticandovi il markdown (c’e’ molto poco da dimenticare) e tramite l’esportazione avrete ottenuto la pagina .MD da caricare.

Ho cosi’ risolto il mio problema! Inoltre avremo i file originali .org che potremmo alla bisogna modificare/esportare/conservare nel vostro git repo preferito.

Biblio