path: root/WORKFLOW.md

# 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
```

### Mark an article as obsolete

Add `obsolete = true` to the article's front matter. Optionally link to a successor article with `successor = "/path/to/article"`:

```toml
+++
title = "My Old Article"
# ... other fields ...
obsolete = true
successor = "/articles/my-new-article"
+++
```

The banner appears automatically below the article header. If `successor` is set, it resolves the article title and links to it. Both EN and IT i18n strings are customizable in `i18n/en.yaml` and `i18n/it.yaml`.

Paths are Hugo permalinks — for English articles, use `/articles/slug`, not `/en/articles/slug`.

---

## 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
```