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
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
|
# Emoji Support Implementation Plan
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
**Goal:** Enable `:shortcode:` emoji syntax in article prose, rendered consistently cross-platform using Twemoji SVGs.
**Architecture:** Hugo converts `:shortcode:` to Unicode at build time via `enableEmoji = true`. At runtime, Twemoji JS (CDN) replaces Unicode emoji inside `.prose` with consistent `<img>` SVG tags. CSS keeps emoji sized and aligned inline with text.
**Tech Stack:** Hugo (enableEmoji), Twemoji CDN (jsdelivr), Tailwind CSS (@apply), Hugo Pipes (JS minification)
---
## File Map
| File | Repo | Action |
|------|------|--------|
| `hugo.toml` | content (`~/Programming/GIT/danix.xyz-hacker-theme/`) | Add `enableEmoji = true` |
| `assets/js/twemoji-init.js` | theme (`~/Programming/GIT/danix2-hugo-theme/`) | Create — init Twemoji on `.prose` |
| `layouts/_default/baseof.html` | theme | Add CDN script + Hugo Pipes script, article-pages only |
| `assets/css/main.css` | theme | Add `.prose img.emoji` sizing rule |
**Note:** `layouts/articles/single.html` does NOT need changes — the script loading is centralised in `baseof.html` using `{{ if eq .Kind "page" }}` guards, matching the existing pattern for reading-progress and code-copy scripts.
---
## Task 1: Enable Hugo emoji parsing
**Files:**
- Modify: `hugo.toml` (content repo root)
- [ ] **Step 1: Add enableEmoji to hugo.toml**
Open `/home/danix/Programming/GIT/danix.xyz-hacker-theme/hugo.toml`. After the `enableRobotsTXT = true` line, add:
```toml
enableEmoji = true
```
Result (lines 1-6 of hugo.toml):
```toml
baseURL = "https://danix.xyz/"
languageCode = "it-IT"
title = "danix.xyz"
theme = "danix-xyz-hacker"
enableRobotsTXT = true
enableEmoji = true
```
- [ ] **Step 2: Verify Hugo parses emoji**
From content repo root, run:
```bash
hugo server --buildDrafts 2>&1 | head -5
```
Expected: Hugo starts without errors.
Then open any article and temporarily add `:grin:` to its content. Confirm it renders as `😁` in the browser (Unicode, no Twemoji yet). Revert the test content change.
- [ ] **Step 3: Commit**
```bash
git add hugo.toml
git commit -m "feat: enable Hugo emoji shortcode parsing"
```
---
## Task 2: Create Twemoji init script
**Files:**
- Create: `assets/js/twemoji-init.js` (theme repo: `~/Programming/GIT/danix2-hugo-theme/`)
- [ ] **Step 1: Create the file**
Create `/home/danix/Programming/GIT/danix2-hugo-theme/assets/js/twemoji-init.js`:
```js
document.addEventListener('DOMContentLoaded', () => {
const prose = document.querySelector('.prose')
if (prose) twemoji.parse(prose, { folder: 'svg', ext: '.svg' })
})
```
- [ ] **Step 2: Commit in theme repo**
```bash
cd ~/Programming/GIT/danix2-hugo-theme
git add assets/js/twemoji-init.js
git commit -m "feat: add Twemoji init script for article prose"
```
---
## Task 3: Load Twemoji CDN + init script on article pages
**Files:**
- Modify: `layouts/_default/baseof.html` (theme repo)
The existing pattern for article-only scripts uses `{{ if eq .Kind "page" }}`. Twemoji must load before `twemoji-init.js` runs — CDN script first, then the local init script.
- [ ] **Step 1: Add CDN and init script block to baseof.html**
Open `/home/danix/Programming/GIT/danix2-hugo-theme/layouts/_default/baseof.html`.
Find the code-copy block (lines 104-108):
```html
<!-- Code block copy button -->
{{ if eq .Kind "page" }}
{{ $codeScript := resources.Get "js/code-copy.js" | minify }}
<script src="{{ $codeScript.RelPermalink }}"></script>
{{ end }}
```
Add the following block immediately after it:
```html
<!-- Twemoji: consistent cross-platform emoji rendering on article pages -->
{{ if eq .Kind "page" }}
<script src="https://cdn.jsdelivr.net/npm/twemoji@14.1.2/dist/twemoji.min.js" crossorigin="anonymous"></script>
{{ $twemojiScript := resources.Get "js/twemoji-init.js" | minify }}
<script src="{{ $twemojiScript.RelPermalink }}"></script>
{{ end }}
```
**Why pinned version (14.1.2) not `@latest`:** `@latest` on jsDelivr can serve stale cached versions. Pin to latest stable for reproducible builds.
- [ ] **Step 2: Verify Hugo builds without errors**
```bash
cd ~/Programming/GIT/danix.xyz-hacker-theme
hugo server --buildDrafts 2>&1 | head -10
```
Expected: no errors, site serves.
- [ ] **Step 3: Commit in theme repo**
```bash
cd ~/Programming/GIT/danix2-hugo-theme
git add layouts/_default/baseof.html
git commit -m "feat: load Twemoji CDN and init script on article pages"
```
---
## Task 4: Add emoji inline sizing CSS
**Files:**
- Modify: `assets/css/main.css` (theme repo)
Twemoji replaces Unicode emoji with `<img class="emoji">` tags. Without CSS they render at their natural size (~72px). This rule keeps them inline at 1em.
- [ ] **Step 1: Add rule to main.css**
Open `/home/danix/Programming/GIT/danix2-hugo-theme/assets/css/main.css`.
Find the prose section (around line 1017, the `html.theme-light .prose` block). Add the following rule before that block:
```css
/* Twemoji inline emoji sizing */
.prose img.emoji {
@apply inline-block;
height: 1em;
width: 1em;
vertical-align: -0.1em;
margin: 0;
}
```
**Note:** `h-[1em]` and `w-[1em]` use arbitrary Tailwind values. Using plain CSS `height`/`width` instead avoids Tailwind's JIT needing to scan for these — simpler and equally correct.
- [ ] **Step 2: Rebuild CSS**
```bash
cd ~/Programming/GIT/danix.xyz-hacker-theme
npm run build
```
Expected: `main.min.css` regenerated with no errors.
- [ ] **Step 3: Commit CSS in theme repo**
```bash
cd ~/Programming/GIT/danix2-hugo-theme
git add assets/css/main.css assets/css/main.min.css
git commit -m "build: add Twemoji emoji inline sizing CSS"
```
---
## Task 5: Bump submodule and verify end-to-end
**Files:**
- Modify: `themes/danix-xyz-hacker` pointer (content repo)
- [ ] **Step 1: Bump submodule pointer**
```bash
cd ~/Programming/GIT/danix.xyz-hacker-theme
git add themes/danix-xyz-hacker
git commit -m "chore: bump theme submodule (emoji support)"
```
- [ ] **Step 2: Push theme repo**
```bash
cd ~/Programming/GIT/danix2-hugo-theme
git push origin master
```
- [ ] **Step 3: Push content repo**
```bash
cd ~/Programming/GIT/danix.xyz-hacker-theme
git push origin master
```
- [ ] **Step 4: End-to-end verification**
Run dev server:
```bash
cd ~/Programming/GIT/danix.xyz-hacker-theme
hugo server --buildDrafts
```
Open an article in browser. Add `:grin: :rocket: :heart:` to the article content temporarily. Verify:
1. Emoji shortcodes render (not raw `:grin:` text)
2. Twemoji SVG `<img>` tags appear in devtools (not plain Unicode chars)
3. Emoji are inline-sized with text — not oversized
4. Non-article pages (homepage, tag lists) do NOT load Twemoji scripts (check Network tab)
5. No console errors
Revert test content. Done.
|
