--- /dev/null
+# 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.
