1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
|
# Hugo Theme Architecture Instructions - danix.xyz
You are the lead software architect for https://danix.xyz. Your code must follow a "Slackware-style" philosophy: clean, essential, and free of bloat.
## 🌍 Multilingual Support (IT/EN)
The site is bilingual (Italian and English). You must:
- **i18n Framework**: Use Hugo’s translation folders (`i18n/it.yaml`, `i18n/en.yaml`) for all UI strings (e.g., "Read more", "Contact me", "Menu").
- **Language Switcher**: Implement a clean language toggle within the hamburger overlay.
- **Logic**: Ensure all templates (Home, Lists, Singles) correctly handle multilingual variables and menus defined in `hugo.toml`.
## 🛠 Tech Stack
- **Hugo (Extended)**: Use Hugo Pipes for asset processing and minification.
- **Tailwind CSS**: Utility-first styling (use `@apply` for semantic components).
- **Alpine.js**: Logic for the overlay menu, language switching, and asynchronous form handling.
- **Vanilla JS**: For minimal optimizations and scripts where Alpine is not required.
## 🧩 Shortcode System (Consensual)
DO NOT write code for shortcodes without consulting the user first. Implement:
1. **Contact Form**: `{{< contact_form >}}` with AJAX handling via Alpine.js targeting `contact.php`. Must support translated labels for fields and error messages.
2. **Gravatar**: Profile image retrieval via email hash.
3. **Images & Galleries**: Responsive, lazy-loading, and caption support.
4. **Video Embeds**: Privacy-friendly YouTube/Vimeo.
**Documentation**: Update `SHORTCODES.md` with usage examples for every tool.
## 🐧 Slackware Project Pages
A dedicated Hugo section (`content/{en,it}/slackware/`) for long-form project
references, distinct from dated articles. The clickable **Slackware** hub
(`/slackware/`) explains why Slackware is used and aggregates every project as
a styled row; each project has its own full page.
- **Authoring**: drop a folder with `index.md` per project; it appears on the
hub automatically. Light front-matter schema: `tagline`, `status` (string
badge: active/maintained/wip/archived), optional `repo_url`, `tags`. Body is
freeform markdown.
- **Images**: inferred by filename as page resources — `thumbnail.*` (3:2 row
image) and `header.*` (wide banner above the project title). Mono-glyph
fallback when no thumbnail.
- **Taxonomy + search**: project `tags` reuse the shared site `tags` taxonomy
(term pages aggregate articles + projects) and projects are in the search
index.
- **Menu**: top-level entries renamed — **Projects** (external → git.danix.xyz)
and a **Slackware** parent whose submenu holds **Packages** (the package-repo
page) and, optionally, project pages. The submenu is a full-width second row
that expands the frosted header on hover/focus (CSS-only, keyboard-accessible).
- See `WORKFLOW.md` → "Working with Slackware Project Pages" for the recipes.
## 🎨 Design & UX
- **Identity**: Maintain the font stack and palettes from `danix.me`.
- **Accent**: Primary Purple. Modern aesthetic with an open-source/hacker soul.
- **Hero**: Full-screen, dynamic text, bio, and profile photo (multilingual bio).
- **Navigation**: Top hamburger menu -> Full-screen overlay (Articles + Pages + Language Toggle - dark/light theme toggle).
- **A11y**: Target WCAG 2.1 AA.
## 📝 Work Protocol
1. **Pianification**: Propose the `i18n` structure and partials layout before writing.
2. **Consultation**: Always ask before implementing complex logic or shortcodes.
3. **KISS**: Keep It Simple, Stupid.
## 🔧 Git Workflow
**Two repos, one site:**
- Content repo: `~/Programming/GIT/danix.xyz-hacker-theme/` → `danix_git:danix.xyz-2`
- Theme repo: `~/Programming/GIT/danix2-hugo-theme/` → `danix_git:danix2-hugo-theme`
- Theme lives as submodule at `themes/danix-xyz-hacker/` in content repo
**Three branches, defined roles:**
- `master`: staging/dev branch. All feature branches merge here. Safe for WIP commits and testing.
- `production`: live branch. Merges only from master when ready to ship. Post-receive hook fires on production pushes only.
- Feature branches: work branches for features, content, or experiments. Merge to master when done.
**Theme work:**
1. Always edit files inside `themes/danix-xyz-hacker/` (the submodule). Never edit `danix2-hugo-theme/` directly and copy over — this causes `main.min.css` to go out of sync with the theme repo.
2. Always `git checkout master` inside the submodule before editing.
3. Commit and push from inside `themes/danix-xyz-hacker/` to `danix2-hugo-theme`.
4. Bump submodule pointer in content repo: `git add themes/danix-xyz-hacker && git commit -m "chore: bump theme submodule" && git push origin master`
**CSS rebuild (after template changes with new Tailwind classes):**
1. From content repo root: `npm run build` (outputs to `themes/danix-xyz-hacker/assets/css/main.min.css`)
2. Commit compiled CSS in submodule: `cd themes/danix-xyz-hacker && git add assets/css/main.min.css && git commit -m "build: recompile CSS" && git push origin master`
3. Bump submodule: `cd .. && git add themes/danix-xyz-hacker && git commit -m "chore: bump theme submodule (CSS rebuild)" && git push origin master`
> ⚠️ `main.min.css` must be committed from inside `themes/danix-xyz-hacker/` — production clones `danix2-hugo-theme` master tip directly, so any compiled CSS not committed there will be missing on deploy.
**Deployment to production:**
1. When master is ready to ship: `git checkout production && git merge master && git push origin production`
2. Post-receive hook clones latest `danix2-hugo-theme` master tip and builds the site
3. Theme changes deploy automatically on next production push (no submodule bump required for deployment, only for local tracking)
## 🎨 Styling & Build Pipeline
- **Tailwind CSS**: Uses npm build pipeline with `tailwind.config.js`
- **CSS Compilation**: Run `npm run build` to compile `main.css` → `main.min.css`
- **Watch Mode**: Run `npm run watch` during development to auto-rebuild CSS when templates change
- **Required Before Commits**: Always rebuild CSS if you modify templates with new Tailwind classes (`npm run build`)
|
