# 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
# then deploy:
git checkout production && git merge master && git push origin production && git checkout 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
# then deploy:
git checkout production && git merge master && git push origin production && git checkout 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
# then deploy:
git checkout production && git merge master && git push origin production && git checkout 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
# then deploy:
git checkout production && git merge master && git push origin production && git checkout 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
# then deploy:
git checkout production && git merge master && git push origin production && git checkout 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`.

### Add an external link to the main menu

Add a menu entry in `hugo.toml` with `params.external = true`:

```toml
[[menus.main]]
  name = "GitHub"
  url = "https://github.com/youruser"
  weight = 10
  [menus.main.params]
    external = true
```

- `name` is used as-is (not looked up in i18n)
- `url` must be a full URL including scheme
- `weight` controls order relative to other menu items
- External links open in a new tab with `rel="noopener noreferrer"` and include a screen-reader-only "(opens in new tab)" label for WCAG 2.1 AA compliance

---

## Working with Slackware Project Pages

The **Slackware** section (`/slackware/`) is a hub that aggregates long-form
project pages — the official reference for each project, distinct from dated
articles. The hub lists every project as a styled row; each project gets its
own full page. Add a project by dropping a folder; it appears on the hub
automatically.

### Add a project

```bash
cd ~/Programming/GIT/danix.xyz-hacker-theme
mkdir -p content/en/slackware/my-project content/it/slackware/my-project
# create index.md in each (see schema below)
# drop the two images in each folder (see image roles below)
git add content/en/slackware/my-project content/it/slackware/my-project
git commit -m "content: add slackware project 'my-project'"
git push origin master
# then deploy:
git checkout production && git merge master && git push origin production && git checkout master
```

### Project front-matter (light schema)

```toml
+++
title    = "My Project"
tagline  = "One-line what-and-why, shown under the title."
status   = "active"          # active | maintained | wip | archived
repo_url = "https://git.danix.xyz/my-project"   # optional, renders a "View repository" button
tags     = ["bash", "slackbuild"]               # shared site taxonomy + tech pills
+++

Freeform markdown body: what it is, how it works, rationale. Any headings
or shortcodes.
```

- **status** → colored badge (theme-aware vars, WCAG-AA text): `active`=green,
  `maintained`=blue, `wip`=amber, `archived`=muted. It's a plain string you
  set by hand — not derived from git.
- **tags** feed BOTH the rendered tech pills AND the global `tags` taxonomy,
  so `/tags/bash/` lists this project alongside any article tagged `bash`.
  Projects are also included in the site search index.
- **tagline** / **repo_url** are optional.

### Image roles (inferred by filename, no front-matter)

Drop these as page resources **inside the project folder** (next to `index.md`):

| File | Role | Recommended size |
|---|---|---|
| `thumbnail.jpg` | Row image on the `/slackware/` hub | 3:2 landscape, ~900×600 |
| `header.jpg` | Full-width banner above the title on the project page | wide, ~1920×480 |

- Any extension works (`.jpg`/`.png`/`.webp`); they're matched as `thumbnail.*` / `header.*`.
- If `thumbnail.*` is absent, the row falls back to a mono-glyph block (first
  two letters of the title on an accent panel).
- If `header.*` is absent, the project page simply has no banner.
- Put copies in BOTH the EN and IT project folders so each language renders
  its own images.

### Add a project to the Slackware submenu (optional)

Projects appear on the hub automatically. To ALSO list one in the desktop
submenu / mobile sub-list under "Slackware", add a menu block to its
front-matter (the label falls back to the page title):

```toml
[menus.main]
  parent = "slackware"
  weight = 10
```

The "Packages" entry (the package-repository page) is always in this submenu,
configured in `hugo.toml`.

### Edit the hub's intro text

The "why Slackware" prose at the top of `/slackware/` is the freeform body of
`content/{en,it}/slackware/_index.md`. Edit it like any markdown; the project
rows render below it.

### Delete a project

```bash
cd ~/Programming/GIT/danix.xyz-hacker-theme
git rm -r content/en/slackware/my-project content/it/slackware/my-project
git commit -m "content: remove slackware project 'my-project'"
git push origin master
# then deploy:
git checkout production && git merge master && git push origin production && git checkout 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` **production branch** triggers the `post-receive` hook on the server. Pushing to `master` alone does NOT deploy.

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`

**Deploy workflow:** commit to master first, then merge into production and push:

```bash
git checkout production && git merge master && git push origin production && git checkout master
```

**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 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, push to master, then merge to production.

---

## 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
git checkout production && git merge master && git push origin production && git checkout 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 in content repo:
cd ~/Programming/GIT/danix.xyz-hacker-theme
git add themes/danix-xyz-hacker && git commit -m "chore: bump theme" && git push origin master
# then deploy:
git checkout production && git merge master && git push origin production && git checkout master

# check submodule status
git submodule status

# update submodule to latest theme
git submodule update --remote themes/danix-xyz-hacker
```