Feature/cosmonauta custom

.github/workflows/deploy-theme.yml

@@ -0,0 +1,41 @@
+name: Deploy Ghost theme
+
+on:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ghost-production-theme
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd
+        with:
+          persist-credentials: false
+
+      - uses: pnpm/action-setup@0e279bb959325dab635dd2c09392533439d90093
+
+      - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e
+        with:
+          node-version: 22.13.0
+          cache: pnpm
+          cache-dependency-path: pnpm-lock.yaml
+
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm test:ci
+
+      - name: Deploy cosmonauta to Ghost
+        uses: TryGhost/action-deploy-theme@v2
+        with:
+          api-url: ${{ secrets.GHOST_ADMIN_API_URL }}
+          api-key: ${{ secrets.GHOST_ADMIN_API_KEY }}
+          theme-name: cosmonauta
+          exclude: node_modules dist

.github/workflows/test.yml

@@ -1,14 +1,17 @@
-name: Test
+name: Validate theme
 
 on:
   pull_request:
+  push:
+    branches:
+      - main
 
 permissions:
   contents: read
 
 jobs:
   test:
-    name: Test
+    name: Validate
     runs-on: ubuntu-latest
 
     steps:
@@ -20,7 +23,7 @@ jobs:
 
       - uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e
         with:
-          node-version: lts/*
+          node-version: 22.13.0
           cache: pnpm
           cache-dependency-path: pnpm-lock.yaml
 

AGENTS.md

@@ -23,3 +23,28 @@ Run the test command before opening a PR when theme files, generated assets, dep
 - Keep generated assets/built/ files in sync when source assets change and the repo tracks those outputs.
 - Do not commit node_modules/, local Ghost content, generated zip files outside tracked release expectations, or secrets.
 - Repo settings, descriptions, and branch rules belong on the GitHub repository; internal clean-repos metadata stays in TryGhost/cleanrepos.
+
+## Cosmonauta customizations
+
+This repository is a fork of TryGhost/Source. Preserve compatibility with
+future Source releases by keeping Cosmonauta-specific changes isolated.
+
+- Put CSS customizations only in `assets/css/custom.css`; the Gulp build
+  appends it after Source's stylesheet.
+- Put JavaScript customizations only in `assets/js/custom.js`; the Gulp build
+  appends it after Source's scripts.
+- Do not modify Source CSS or JavaScript for a local customization when one of
+  the `custom.*` files can implement it.
+- When a `.hbs` template or partial must change, make the smallest possible
+  edit and wrap every local block with these Handlebars comments:
+
+  ```hbs
+  {{!-- COSMONAUTA CUSTOM: inizio — description --}}
+  {{!-- local code --}}
+  {{!-- COSMONAUTA CUSTOM: fine — description --}}
+  ```
+
+- Use equivalent `COSMONAUTA CUSTOM: inizio` / `fine` comments for isolated
+  exceptions outside the `custom.*` files.
+- Never edit `assets/built/` files by hand; regenerate them with `pnpm build`
+  (or `pnpm dev`) after source changes.

README.md

@@ -1,97 +1,162 @@
-# Source
+# Cosmonauta
 
-The default theme for [Ghost](http://github.com/tryghost/ghost/). This is the latest development version of Source! If you're just looking to download the latest release, head over to the [releases](https://github.com/TryGhost/Source/releases) page.
+Tema personalizzato di [Ghost](https://ghost.org/) per cosmonauta.dev. È un fork di [TryGhost/Source](https://github.com/TryGhost/Source), mantenuto per integrare in modo controllato le release ufficiali di Source.
 
- 
+## Architettura Git
 
-# First time using a Ghost theme?
+Questo è un repository Git indipendente, anche se la directory `cosmonauta_theme/` si trova nel workspace del repository infrastrutturale. Il repository padre lo ignora e non deve mai aggiungerne file o commit.
 
-Ghost uses a simple templating language called [Handlebars](http://handlebarsjs.com/) for its themes.
+- `origin`: `git@github.com:arrubiu/cosmonauta_theme.git`, il fork di Cosmonauta.
+- `upstream`: `https://github.com/TryGhost/Source.git`, il tema ufficiale Ghost.
+- `main`: la sola branch distribuita in produzione.
 
-This theme has lots of code comments to help explain what's going on just by reading the code. Once you feel comfortable with how everything works, we also have full [theme API documentation](https://ghost.org/docs/themes/) which explains every possible Handlebars helper and template.
+Verificare la configurazione con:
 
-**The main files are:**
-
-- `default.hbs` - The parent template file, which includes your global header/footer
-- `home.hbs` - The homepage
-- `index.hbs` - The main template to generate a list of posts
-- `post.hbs` - The template used to render individual posts
-- `page.hbs` - Used for individual pages
-- `tag.hbs` - Used for tag archives, eg. "all posts tagged with `news`"
-- `author.hbs` - Used for author archives, eg. "all posts written by Jamie"
-
-One neat trick is that you can also create custom one-off templates by adding the slug of a page to a template file. For example:
-
-- `page-about.hbs` - Custom template for an `/about/` page
-- `tag-news.hbs` - Custom template for `/tag/news/` archive
-- `author-ali.hbs` - Custom template for `/author/ali/` archive
+```sh
+git remote -v
+```
 
+## Prerequisiti
 
-# Development
+Servono Node 22, Corepack/pnpm e accesso al repository GitHub.
 
-Source styles are compiled using Gulp/PostCSS to polyfill future CSS spec. You'll need [Node](https://nodejs.org/) and [pnpm](https://pnpm.io/). After that, from the theme's root directory:
+```sh
+node --version
+corepack --version
+pnpm --version
+```
 
-```bash
-# install dependencies
-pnpm install
+Il file `package.json` richiede Node almeno `22.12.0`; la CI usa Node `22.13.0`, compatibile con pnpm 11.22. Se necessario, attivare Corepack:
 
-# run development server
-pnpm dev
+```sh
+corepack enable
 ```
 
-Now you can edit `/assets/css/` files, which will be compiled to `/assets/built/` automatically.
+## Sviluppo quotidiano
 
-The `zip` Gulp task packages the theme files into `dist/<theme-name>.zip`, which you can then upload to your site.
+Dalla root di questo repository:
 
-```bash
-# create .zip file
-pnpm zip
+```sh
+pnpm install --frozen-lockfile
+git switch -c feature/nome-modifica
+# modificare template, CSS, JavaScript o asset
+pnpm test:ci
+git add -A
+git commit -m "feat: descrizione della modifica"
+git push -u origin feature/nome-modifica
 ```
 
-# Publishing a release
-
-Releases are shipped from an up-to-date, clean `main` branch in two steps. Before starting, configure `GST_TOKEN` with a GitHub token that can create releases in `TryGhost/Source`.
+Aprire una pull request verso `main` e fare il merge solo quando la CI è verde. Solo un push risultante dal merge in `main` esegue il deploy su Ghost produzione; branch e pull request non ricevono segreti né pubblicano modifiche.
+
+## Personalizzazioni Cosmonauta e compatibilità con Source
+
+Questo tema deve restare il più possibile compatibile con le future release di
+[TryGhost/Source](https://github.com/TryGhost/Source). Per ogni modifica
+specifica di Cosmonauta, applicare queste regole.
+
+- Mettere tutte le regole CSS locali in `assets/css/custom.css`. Il build Gulp
+  lo aggiunge dopo `assets/css/screen.css` e lo compila nel consueto
+  `assets/built/screen.css`.
+- Mettere tutti i comportamenti JavaScript locali in `assets/js/custom.js`.
+  Il build Gulp lo concatena per ultimo in `assets/built/source.js`, dopo gli
+  script di Source.
+- Non modificare CSS o JavaScript originali di Source per introdurre una
+  personalizzazione quando i file `custom.*` possono risolverla. Usare
+  selettori mirati e limitare `!important` ai casi in cui non esista
+  un'alternativa affidabile.
+- Se è indispensabile modificare un template o un partial `.hbs`, mantenere
+  l'intervento strettamente locale e racchiuderlo sempre in commenti
+  Handlebars che ne indicano chiaramente inizio e fine:
+
+  ```hbs
+  {{!-- COSMONAUTA CUSTOM: inizio — breve descrizione --}}
+  {{!-- codice locale --}}
+  {{!-- COSMONAUTA CUSTOM: fine — breve descrizione --}}
+  ```
+
+- Applicare la stessa delimitazione ai cambiamenti non-template che non
+  possono vivere nei file `custom.*`, scegliendo il commento appropriato al
+  linguaggio (`COSMONAUTA CUSTOM: inizio` / `fine`).
+- Dopo modifiche a CSS o JavaScript eseguire `pnpm build` (oppure mantenere
+  attivo `pnpm dev`) e verificare che `assets/built/` sia aggiornato. Prima di
+  una pull request eseguire sempre `pnpm test:ci`.
+
+I file `assets/built/` sono artefatti tracciati: non modificarli a mano. Le
+personalizzazioni devono essere apportate ai sorgenti e rigenerate dal build.
+
+## Anteprima locale senza ZIP
+
+Il repository infrastrutturale monta questa directory nel Ghost locale come
+`/var/lib/ghost/content/themes/cosmonauta`. Dalla root del repository
+infrastrutturale avviare Ghost, poi lasciare il watcher del tema attivo:
+
+```sh
+./local.sh up
+cd cosmonauta_theme
+pnpm install --frozen-lockfile
+pnpm dev
+```
 
-First bump the version. This updates `package.json`, then creates a commit and annotated `v<version>` git tag:
+In Ghost Admin locale (`http://localhost:2368/ghost`) attivare `cosmonauta`
+da **Settings → Design**. Le modifiche a CSS e JavaScript sono ricompilate dal
+watcher; dopo modifiche a file `.hbs` o `package.json`, eseguire
+`./local.sh restart` dalla root del repository infrastrutturale. Questo mount
+esiste solo nell'ambiente locale e non carica nulla in produzione.
 
-```bash
-# pick one of: patch | minor | major (or an explicit version, e.g. 1.8.0)
-pnpm version minor
-```
+## Deploy iniziale e rollback
 
-Then run `ship`:
+1. In Ghost Admin creare una Custom Integration chiamata `GitHub Actions`.
+2. Nel repository GitHub, aggiungere i secret Actions `GHOST_ADMIN_API_URL` e `GHOST_ADMIN_API_KEY` con i valori dell’integrazione.
+3. Fare merge in `main` e verificare il workflow **Deploy Ghost theme** nella scheda Actions.
+4. Dopo il primo deploy, attivare `cosmonauta` una volta in Ghost Admin → Design.
 
-```bash
-pnpm ship
-```
+I deploy successivi aggiornano il tema già attivo. Per annullare una pubblicazione errata, fare il revert del merge su `main`; il nuovo push ridistribuisce la versione precedente.
 
-`pnpm ship`:
+## Ricevere gli aggiornamenti ufficiali
 
-1. Builds the theme zip and runs GScan.
-2. Refuses to continue if the working tree is not clean after the build.
-3. Pushes the version commit and tag.
-4. Prompts for the minimum compatible Ghost version and creates a draft GitHub release with the generated changelog.
+Su [TryGhost/Source](https://github.com/TryGhost/Source), selezionare **Watch → Custom → Releases**. Le notifiche segnalano nuove release stabili. Non usare il pulsante GitHub **Sync fork**, perché sincronizza il ramo di sviluppo anziché la release scelta.
 
-Review and publish the draft GitHub release after the command completes. The pushed theme tag, rather than the GitHub release, is what the next Ghost release uses when updating its bundled Source theme.
+## Aggiornare da una release di Source
 
-> [!NOTE]
-> `pnpm version` requires an explicit version or bump type. Run it before `pnpm ship`; the ship command does not perform the bump itself.
+Per ricevere e preparare un aggiornamento ufficiale, dalla root di questo
+repository eseguire:
 
-# PostCSS Features Used
+```sh
+./theme.sh update
+```
 
-- Autoprefixer - Don't worry about writing browser prefixes of any kind, it's all done automatically with support for the latest 2 major versions of every browser.
+Lo script richiede un worktree pulito e la branch locale `main`. Confronta il
+tag ufficiale più recente con quello già integrato, poi esegue il merge con
+`--no-commit` su un nuovo branch locale `update/source-<tag>`: non crea
+commit, non fa push e non apre pull request. `main` resta invariata. Prosegue
+con build, riavvio di Ghost locale e `./local.sh sync --yes`.
 
+> [!WARNING]
+> Il sync sostituisce completamente database e upload di Ghost locale con la
+> produzione. Il codice del tema non viene sostituito, perché è montato dalla
+> directory `cosmonauta_theme/`.
 
-# SVG Icons
+Dopo il sync, attivare `cosmonauta` in Ghost Admin locale e verificarlo su
+`http://localhost:2368`. Se l’aggiornamento è valido, committare il merge sul
+branch `update/source-<tag>` e seguire la normale PR verso `main`. Per
+annullare la prova locale, eseguire `git merge --abort`. Se trova conflitti,
+build o sync falliti, lo script non perde il merge locale e indica il rollback
+sicuro.
 
-Source uses inline SVG icons, included via Handlebars partials. You can find all icons inside `/partials/icons`. To use an icon just include the name of the relevant file, eg. To include the SVG icon in `/partials/icons/rss.hbs` - use `{{> "icons/rss"}}`.
+## Comando build locale
 
-You can add your own SVG icons in the same manner.
+```sh
+./theme.sh build
+```
 
-# Translations
+Rigenera CSS, JavaScript e traduzioni con `pnpm build`. Se Ghost locale è in
+configurato, lo avvia o riavvia per ricaricare il tema.
 
-Please see [@TryGhost/Themes/theme-translations/README.md](https://github.com/TryGhost/Themes/blob/main/packages/theme-translations/README.md) for how to build, edit, or contribute translations.
+## Verifica locale
 
-# Copyright & License
+```sh
+pnpm test:ci
+pnpm zip
+```
 
-Copyright (c) 2013-2026 Ghost Foundation - Released under the [MIT license](LICENSE).
+`pnpm test:ci` crea il pacchetto e lo controlla con GScan per la compatibilità Ghost. L’archivio generato in `dist/` è locale e non va versionato.