From: Danilo M. Date: Thu, 30 Apr 2026 11:37:39 +0000 (+0200) Subject: docs: add emoji support implementation plan X-Git-Tag: release_30042026-1419~8 X-Git-Url: https://git.danix.xyz/?a=commitdiff_plain;h=0b5245e97898e239e3ae7abeacbdb8d31e865539;p=danix.xyz-2.git docs: add emoji support implementation plan Co-Authored-By: Claude Sonnet 4.6 --- diff --git a/docs/superpowers/plans/2026-04-30-emoji-support.md b/docs/superpowers/plans/2026-04-30-emoji-support.md new file mode 100644 index 0000000..936745a --- /dev/null +++ b/docs/superpowers/plans/2026-04-30-emoji-support.md @@ -0,0 +1,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 `` 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 + + {{ if eq .Kind "page" }} + {{ $codeScript := resources.Get "js/code-copy.js" | minify }} + + {{ end }} +``` + +Add the following block immediately after it: +```html + + + {{ if eq .Kind "page" }} + + {{ $twemojiScript := resources.Get "js/twemoji-init.js" | minify }} + + {{ 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 `` 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 `` 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.