# Emoji Support — Design Spec

**Date:** 2026-04-30
**Status:** Approved

## Problem

Authors can't use `:grin:` emoji shortcodes in article prose. Hugo's default config ignores them; no consistent cross-platform rendering exists.

## Scope

Article prose only (`.prose` div in `layouts/articles/single.html`). Not titles, excerpts, tags, or UI chrome.

## Approach

Two-layer solution:

1. **Build time** — Hugo's `enableEmoji = true` converts `:shortcode:` syntax to Unicode emoji characters during markdown rendering.
2. **Runtime** — Twemoji JS (CDN) replaces Unicode emoji inside `.prose` with consistent SVG `<img>` tags.

## Components

### 1. hugo.toml — `enableEmoji`

Add to top-level config in `/home/danix/Programming/GIT/danix.xyz-hacker-theme/hugo.toml`:

```toml
enableEmoji = true
```

Enables Hugo's built-in Go emoji library. Converts GitHub-style `:shortcode:` to Unicode at build time. No other markup changes needed.

### 2. Twemoji init script

New file: `assets/js/twemoji-init.js` in theme repo (`/home/danix/Programming/GIT/danix2-hugo-theme/`).

```js
document.addEventListener('DOMContentLoaded', () => {
  const prose = document.querySelector('.prose')
  if (prose) twemoji.parse(prose, { folder: 'svg', ext: '.svg' })
})
```

Targets `.prose` only. SVG format for crisp rendering at any size. Loaded via Hugo Pipes (minified), consistent with all other JS in the theme.

### 3. Twemoji CDN script tag

In `layouts/articles/single.html` (theme repo), add before closing `</body>` or in the scripts block:

```html
<script src="https://cdn.jsdelivr.net/npm/twemoji@latest/dist/twemoji.min.js" crossorigin="anonymous"></script>
```

Loaded only on article pages — matches existing conditional JS loading pattern in `baseof.html`.

### 4. CSS — inline emoji sizing

In `assets/css/main.css` (theme repo), add under prose styles:

```css
.prose img.emoji {
  @apply inline-block h-[1em] w-[1em] align-[-0.1em];
}
```

Twemoji adds class `emoji` to generated `<img>` tags. This keeps emoji inline with text at correct optical size.

## Accessibility

Default Twemoji output sets `alt` to the Unicode emoji character (e.g., `alt="😁"`). Screen readers announce the Unicode name ("grinning face"). Passes WCAG 2.1 AA. No override needed.

## Emoji Shortcode Reference

Uses GitHub emoji shortcode names. Reference: search "github emoji cheat sheet" for the full list.

## Files Changed

| File | Repo | Change |
|------|------|--------|
| `hugo.toml` | content | Add `enableEmoji = true` |
| `assets/js/twemoji-init.js` | theme | New file — Twemoji init targeting `.prose` |
| `layouts/articles/single.html` | theme | Add Twemoji CDN `<script>` tag |
| `assets/css/main.css` | theme | Add `.prose img.emoji` sizing rule |

## Build Notes

- CSS rebuild required (`npm run build`) after adding Tailwind classes to `main.css`
- Submodule bump required after theme changes
- No new npm dependencies