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