Skip to main content

Creare e sviluppare un tema

Un tema è una cartella di file di testo (template, sezioni, snippet, CSS) che Riseact pubblica in versioni immutabili. Le organizzazioni installano una versione e decidono quando aggiornare.

Serve un account Partner: vedi la guida iniziale.

Installare la CLI

Scarica la versione per il tuo sistema dalla pagina delle release e metti l'eseguibile nel PATH. Poi autenticati:

riseact auth login

Partire da un tema esistente

riseact theme init

Clona un tema di partenza, chiede i dati del manifest.json (nome, identificativo, versione, autore) e crea una cartella con il nome dell'identificativo. Il contenuto delle sottocartelle è descritto in struttura di un tema.

L'identificativo è definitivo: Lega tra loro le versioni dello stesso tema e non si può cambiare. Il comando ti avverte se è già occupato.

Per ripartire da una versione già pubblicata:

riseact theme pull -p ./cartella-vuota

Chiede tema e versione e ne scarica i file.

Sviluppare con l'anteprima dal vivo

cd il-tuo-tema
riseact theme dev

Alla prima esecuzione chiede su quale organizzazione lavorare e ci installa il tema, poi stampa due indirizzi: l'anteprima e l'editor visuale nel pannello.

Il tema resta nella libreria dell'organizzazione senza essere pubblicato: il sito visto dai donatori non cambia. Ctrl+C non cancella niente, e il prossimo theme dev nella stessa cartella riprende da lì.

Se non hai un'organizzazione su cui lavorare, creane una di sviluppo: è gratuita e senza dati reali.

La sincronizzazione va nei due sensi

Finché theme dev è in esecuzione, cartella e tema restano allineati:

  • un file salvato in locale viene caricato subito: basta ricaricare l'anteprima;
  • una modifica salvata dall'editor visuale aggiorna il file nella cartella.

Così colori, testi e composizione delle pagine si scelgono dall'editor: componi la homepage trascinando le sezioni e templates/homepage.json si aggiorna da sé. È quel file a finire nella release e a definire l'aspetto del tema appena installato.

All'avvio il comando riallinea le due parti, quindi ritrovi anche le modifiche fatte dall'editor a comando spento.

Nota: In caso di conflitto vince la modifica più recente. Se lo stesso file è cambiato da entrambe le parti a comando spento, vince la copia sul server e il nome del file viene stampato.

Tema e organizzazione della sessione sono salvati in .riseact/dev.json. Aggiungi .riseact/ al .gitignore; se lo cancelli, il prossimo theme dev riparte da un tema nuovo.

Cancellare file

Le cancellazioni si propagano solo mentre theme dev è in esecuzione. Un file cancellato a comando spento viene riscaricato dal server al riavvio.

Escludere file dal caricamento

Gli strumenti di build vanno elencati in .riseactignore, nella radice del tema, con la sintassi di .gitignore:

node_modules
package.json
package-lock.json
yarn.lock
tailwind.config.js
riseact.yml

Le regole valgono sia per il pacchetto sia per theme dev. .git, node_modules e .riseact sono sempre esclusi.

Pericolo: Includi sempre riseact.yml: contiene le credenziali della CLI e altrimenti verrebbe caricato con il tema.

L'output compilato invece va caricato: con Tailwind, per esempio, assets/main.css.

Pubblicare una versione

Quando il tema è pronto, alza la versione nel manifest.json e pubblica:

riseact theme release

Il comando apre l'editor per il changelog. Le organizzazioni lo leggono prima di aggiornare: scrivi cosa cambia, non come. Un messaggio vuoto annulla la pubblicazione.

L'editor è il primo disponibile tra $VISUAL, $EDITOR, la chiave editor nel file di configurazione, git config core.editor e nano.

In alternativa, riseact theme package prepara uno zip da caricare dall'area Partner, con le stesse regole di validazione.

Regole di versionamento

La versione è nel formato MAJOR.MINOR.PATCH (per esempio 1.4.0), senza suffissi come 1.4.0-beta. La pubblicazione viene rifiutata se:

  • la versione è già stata pubblicata per quel tema
  • la versione è inferiore all'ultima pubblicata
  • il changelog è vuoto
  • un file non compila, o il blocco {% schema %} di una sezione non è JSON valido

Se ci sono errori nei file, la risposta li elenca tutti con il percorso e nessuna versione viene creata.

Le versioni sono immutabili

Una versione pubblicata non si modifica: per correggere qualcosa se ne pubblica una nuova.

Cosa vede l'organizzazione

In Temi, ogni tema installato ha il pulsante Versione tema, da cui l'organizzazione può:

  • scegliere una versione dall'elenco e leggerne il changelog
  • vedere quali file modificati da lei verrebbero sovrascritti
  • aggiornare il tema, oppure installare quella versione come tema separato

Si aggiorna solo in avanti. Una versione precedente si installa come tema separato.

Cosa l'aggiornamento conserva

fileall'aggiornamento
sections/, snippets/, layout/, assets/, config/settings_schema.json, templates/**/*.htmlsostituiti dalla nuova versione
config/settings_data.jsonconservato; le impostazioni nuove vengono aggiunte con il loro valore predefinito
templates/**/*.jsonconservati; i template nuovi della versione vengono aggiunti

Il codice del tema è tuo, le scelte dell'organizzazione sono sue. Una modifica all'HTML di una sezione arriva a tutti; una sezione aggiunta a templates/homepage.json arriva solo a chi installa il tema da zero.

Attenzione: Se rinomini o rimuovi una sezione, i template delle organizzazioni che la usano mostrano un errore al suo posto. Non rinominare le sezioni e non eliminare quelle sostituite.

Distribuire il tema

Le nuove versioni sono subito disponibili per le organizzazioni che hanno già il tema. Per renderlo installabile da altre, dalla pagina del tema nell'area Partner scegli:

  • Le mie organizzazioni: lo trovano nello store dei temi tutte quelle che amministri, senza approvazione;
  • Invia per l'approvazione: compare nello store dei temi di tutte le organizzazioni Riseact, dopo una nostra revisione con risposta via email.

Dettagli in Area partner: Temi.

Fonte: https://dev.riseact.org/docs/themes/development. Copia automatica da dev.riseact.org: non modificare qui, le modifiche vanno fatte sulla documentazione Docusaurus.

Back to top