Chore: added WORKFLOW.md and updated git-post-receive hookrelease_22042026-1342

1 files changed, 252 insertions, 0 deletions

diff --git a/WORKFLOW.md b/WORKFLOW.md
new file mode 100644
index 0000000..f8e6fee
--- /dev/null
+++ b/WORKFLOW.md
@@ -0,0 +1,252 @@
+# danix.xyz — Git Workflow Reference
+
+Two repositories, one site:
+
+| Local path | Remote | Purpose |
+|---|---|---|
+| `~/Programming/GIT/danix.xyz-hacker-theme/` | `danix_git:danix.xyz-2` | Content, config, i18n, static assets |
+| `~/Programming/GIT/danix2-hugo-theme/` | `danix_git:danix2-hugo-theme` | Theme layouts, CSS, JS, shortcodes |
+
+The theme lives inside the content repo as a git submodule at `themes/danix-xyz-hacker/`.
+That directory is a full clone of `danix2-hugo-theme` — you can push from there or from the standalone folder.
+
+---
+
+## Working on Content
+
+All content work happens in `~/Programming/GIT/danix.xyz-hacker-theme/`.
+
+### Add a new article
+
+```bash
+cd ~/Programming/GIT/danix.xyz-hacker-theme
+hugo new content/en/articles/my-new-article/index.md
+# write the article, add images to the same directory
+git add content/en/articles/my-new-article/
+git commit -m "content: add article 'my-new-article'"
+git push origin master
+```
+
+### Edit an existing article
+
+```bash
+cd ~/Programming/GIT/danix.xyz-hacker-theme
+# edit the file
+git add content/en/articles/my-article/index.md
+git commit -m "content: update 'my-article'"
+git push origin master
+```
+
+### Delete an article
+
+```bash
+cd ~/Programming/GIT/danix.xyz-hacker-theme
+git rm -r content/en/articles/my-article/
+git commit -m "content: remove 'my-article'"
+git push origin master
+```
+
+### Add a static asset (image, font, file)
+
+Files under `static/` are served at the site root.
+
+```bash
+cp ~/Downloads/photo.jpg static/images/photo.jpg
+git add static/images/photo.jpg
+git commit -m "content: add photo.jpg"
+git push origin master
+```
+
+### Update site config (hugo.toml, i18n strings)
+
+```bash
+# edit hugo.toml or i18n/it.yaml / i18n/en.yaml
+git add hugo.toml
+git commit -m "config: ..."
+git push origin master
+```
+
+---
+
+## Working on the Theme
+
+You have two equivalent ways to edit the theme. Pick one based on context.
+
+---
+
+### Option A — From the standalone theme folder (preferred for theme-only work)
+
+```bash
+cd ~/Programming/GIT/danix2-hugo-theme
+# edit layouts, assets, JS, CSS...
+git add .
+git commit -m "feat: ..."
+git push origin master
+```
+
+Then update the submodule pointer in the content repo so the new commit is tracked:
+
+```bash
+cd ~/Programming/GIT/danix.xyz-hacker-theme
+git add themes/danix-xyz-hacker
+git commit -m "chore: bump theme submodule"
+git push origin master
+```
+
+---
+
+### Option B — From inside the submodule (convenient when testing with real content)
+
+```bash
+cd ~/Programming/GIT/danix.xyz-hacker-theme/themes/danix-xyz-hacker
+git checkout master   # always do this — submodule starts in detached HEAD after update
+# edit files
+git add .
+git commit -m "feat: ..."
+git push origin master
+```
+
+Then bump the pointer in the parent repo:
+
+```bash
+cd ~/Programming/GIT/danix.xyz-hacker-theme
+git add themes/danix-xyz-hacker
+git commit -m "chore: bump theme submodule"
+git push origin master
+```
+
+---
+
+### Rebuild CSS after changing templates or Tailwind classes
+
+```bash
+cd ~/Programming/GIT/danix.xyz-hacker-theme
+npm run build
+# then commit the compiled CSS inside the theme
+cd themes/danix-xyz-hacker
+git add assets/css/main.min.css
+git commit -m "build: recompile CSS"
+git push origin master
+# then bump pointer
+cd ..
+git add themes/danix-xyz-hacker
+git commit -m "chore: bump theme submodule (CSS rebuild)"
+git push origin master
+```
+
+---
+
+## Production Deployment
+
+Pushing to `danix_git:danix.xyz-2` (master) triggers the `post-receive` hook on the server.
+
+The hook:
+1. Creates a fresh Hugo site in `/tmp/danix.xyz-compile`
+2. Checks out the content repo there
+3. Clones the **latest tip of `danix2-hugo-theme` master** into `themes/dagreynix`
+4. Runs `hugo -t dagreynix --minify`
+5. Publishes to `/var/www/html`
+
+**Important:** The hook always clones the current tip of the theme repo — it does NOT use the submodule pointer. This means:
+
+- Pushing a theme change to `danix_git:danix2-hugo-theme` is enough for production to pick it up on the next content deploy.
+- You do NOT need to bump the submodule pointer to deploy theme changes. The pointer is for local tracking only.
+- If you want to deploy a theme change immediately without a content change, make any trivial commit in the content repo and push it.
+
+---
+
+## Edge Cases
+
+### I edited the theme from Option B but forgot `git checkout master` first
+
+You committed to a detached HEAD — the commit exists but is not on any branch.
+
+```bash
+cd ~/Programming/GIT/danix.xyz-hacker-theme/themes/danix-xyz-hacker
+git log --oneline | head -5         # note the commit SHA, e.g. abc1234
+git checkout master
+git cherry-pick abc1234             # apply the detached commit onto master
+git push origin master
+```
+
+Then bump the pointer as usual.
+
+---
+
+### I forgot to bump the submodule pointer after pushing theme changes
+
+No problem. Do it now:
+
+```bash
+cd ~/Programming/GIT/danix.xyz-hacker-theme
+git submodule update --remote themes/danix-xyz-hacker   # fetch latest theme commit
+git add themes/danix-xyz-hacker
+git commit -m "chore: bump theme submodule"
+git push origin master
+```
+
+---
+
+### The submodule is out of sync after pulling the content repo on another machine
+
+```bash
+cd ~/Programming/GIT/danix.xyz-hacker-theme
+git pull origin master
+git submodule update --init --recursive
+```
+
+---
+
+### Fresh clone on a new machine
+
+```bash
+git clone --recurse-submodules danix_git:danix.xyz-2 danix.xyz-hacker-theme
+cd danix.xyz-hacker-theme
+npm install   # restore Tailwind build pipeline
+```
+
+If you forgot `--recurse-submodules`:
+
+```bash
+git submodule update --init --recursive
+```
+
+---
+
+### I want to pin production to a specific theme version (not latest tip)
+
+This requires changing the hook on the server. The current hook always clones master tip, so there is no pinning without modifying `git-post-receive` on the server to use `git clone --branch <tag>` or `git checkout <sha>` after cloning.
+
+For now, treat `danix2-hugo-theme` master as the production branch — don't push broken theme commits there.
+
+---
+
+### I want to check what theme commit is currently deployed
+
+```bash
+ssh danix_git "git -C ~/repositories/danix2-hugo-theme.git log --oneline | head -1"
+```
+
+---
+
+## Quick Reference
+
+```
+# content change → deploy
+cd ~/Programming/GIT/danix.xyz-hacker-theme
+git add <files> && git commit -m "..." && git push origin master
+
+# theme change → deploy
+cd ~/Programming/GIT/danix2-hugo-theme        # or themes/danix-xyz-hacker/
+git checkout master
+git add <files> && git commit -m "..." && git push origin master
+# then bump pointer:
+cd ~/Programming/GIT/danix.xyz-hacker-theme
+git add themes/danix-xyz-hacker && git commit -m "chore: bump theme" && git push origin master
+
+# check submodule status
+git submodule status
+
+# update submodule to latest theme
+git submodule update --remote themes/danix-xyz-hacker
+```