path: root/docs/superpowers/plans/2026-04-17-social-share-widget.md

# Social Sharing Widget 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:** Add a reusable icon-only social sharing widget (9 targets) to the sidebar and as an inline embed on the repository page.

**Architecture:** A single partial `social-share.html` accepts a `mode` parameter (`sidebar` or `inline`) that controls grid layout. Sidebar mode uses a 2-column grid; inline mode uses a 5-column centered grid. Alpine.js handles clipboard copy with icon swap feedback. Brand icons are inline SVGs styled to match Feather Icons visually.

**Tech Stack:** Hugo partials, Alpine.js (already loaded), Feather Icons (already loaded via CDN), Tailwind CSS utility classes, Hugo i18n.

---

## File Map

| Action | Path | Purpose |
|---|---|---|
| Create | `themes/danix-xyz-hacker/layouts/partials/social-share.html` | The widget partial — all 9 buttons, both modes |
| Modify | `themes/danix-xyz-hacker/layouts/partials/sidebar.html` | Add sidebar call between author and related posts |
| Modify | `themes/danix-xyz-hacker/layouts/repository/list.html` | Add inline call after `.Content`, before cards |
| Modify | `themes/danix-xyz-hacker/i18n/en.yaml` | Add 7 new sharing keys |
| Modify | `themes/danix-xyz-hacker/i18n/it.yaml` | Add 7 new sharing keys (Italian) |
| Modify | `i18n/en.yaml` | Keep in sync with theme i18n |
| Modify | `i18n/it.yaml` | Keep in sync with theme i18n |

---

## Task 1: Add i18n Keys to All Four Translation Files

**Files:**
- Modify: `themes/danix-xyz-hacker/i18n/en.yaml`
- Modify: `themes/danix-xyz-hacker/i18n/it.yaml`
- Modify: `i18n/en.yaml`
- Modify: `i18n/it.yaml`

- [ ] **Step 1: Add keys to `themes/danix-xyz-hacker/i18n/en.yaml`**

The file currently has a `# Sharing` section ending at `facebook: "Facebook"` (line 39). Append these keys immediately after `facebook`:

```yaml
# Sharing
share: "Share"
shareOn: "Share on"
copyLink: "Copy link"
twitter: "Twitter"
facebook: "Facebook"
reddit: "Reddit"
pinterest: "Pinterest"
whatsapp: "WhatsApp"
telegram: "Telegram"
signal: "Signal"
shareViaEmail: "Share via email"
linkCopied: "Link copied!"
```

- [ ] **Step 2: Add keys to `themes/danix-xyz-hacker/i18n/it.yaml`**

Same section, currently ending at `facebook: "Facebook"` (line 39). Replace that section with:

```yaml
# Sharing
share: "Condividi"
shareOn: "Condividi su"
copyLink: "Copia link"
twitter: "Twitter"
facebook: "Facebook"
reddit: "Reddit"
pinterest: "Pinterest"
whatsapp: "WhatsApp"
telegram: "Telegram"
signal: "Signal"
shareViaEmail: "Condividi via email"
linkCopied: "Link copiato!"
```

- [ ] **Step 3: Add keys to `i18n/en.yaml`**

This file has a `# Sharing` section. Add the same 7 new keys after `facebook`:

```yaml
reddit: "Reddit"
pinterest: "Pinterest"
whatsapp: "WhatsApp"
telegram: "Telegram"
signal: "Signal"
shareViaEmail: "Share via email"
linkCopied: "Link copied!"
```

- [ ] **Step 4: Add keys to `i18n/it.yaml`**

Same as above for Italian:

```yaml
reddit: "Reddit"
pinterest: "Pinterest"
whatsapp: "WhatsApp"
telegram: "Telegram"
signal: "Signal"
shareViaEmail: "Condividi via email"
linkCopied: "Link copiato!"
```

- [ ] **Step 5: Verify Hugo builds without i18n warnings**

```bash
hugo -D 2>&1 | grep -i "i18n\|warn\|error" | head -20
```

Expected: no i18n-related warnings or errors.

- [ ] **Step 6: Commit**

```bash
git add themes/danix-xyz-hacker/i18n/en.yaml themes/danix-xyz-hacker/i18n/it.yaml i18n/en.yaml i18n/it.yaml
git commit -m "i18n: add social sharing translation keys (EN + IT)"
```

---

## Task 2: Create the Social Share Partial

**Files:**
- Create: `themes/danix-xyz-hacker/layouts/partials/social-share.html`

- [ ] **Step 1: Create the partial with full content**

Create `themes/danix-xyz-hacker/layouts/partials/social-share.html` with the following complete content:

```html
{{ $page := .page }}
{{ $mode := .mode | default "sidebar" }}
{{ $url := $page.Permalink | urlquery }}
{{ $title := $page.Title | urlquery }}

{{ $gridClass := "grid-cols-2 gap-2" }}
{{ if eq $mode "inline" }}
  {{ $gridClass = "grid-cols-5 gap-3 justify-items-center" }}
{{ end }}

<div class="p-4 border border-border/30 rounded mb-6">
  <h3 class="text-lg font-semibold text-accent mb-3">{{ i18n "share" }}</h3>
  <nav aria-label="{{ i18n "share" }}">
    <div class="grid {{ $gridClass }}">

      <!-- Copy link -->
      <div x-data="{ copied: false }">
        <button
          @click="navigator.clipboard.writeText('{{ $page.Permalink }}').then(() => { copied = true; setTimeout(() => copied = false, 2000) })"
          :aria-label="copied ? '{{ i18n "linkCopied" }}' : '{{ i18n "copyLink" }}'"
          class="btn-icon hover:text-accent hover:bg-surface transition-colors focus-visible:ring-2 focus-visible:ring-accent"
        >
          <i x-show="!copied" data-feather="copy" class="w-5 h-5" aria-hidden="true"></i>
          <i x-show="copied" data-feather="check" class="w-5 h-5 text-accent2" aria-hidden="true"></i>
        </button>
      </div>

      <!-- Email -->
      <a
        href="mailto:?subject={{ $title }}&body={{ $title }}%0A%0A{{ $page.Permalink | urlquery }}"
        aria-label="{{ i18n "shareViaEmail" }}"
        class="btn-icon hover:text-accent hover:bg-surface transition-colors focus-visible:ring-2 focus-visible:ring-accent"
      >
        <i data-feather="mail" class="w-5 h-5" aria-hidden="true"></i>
      </a>

      <!-- Facebook -->
      <a
        href="https://www.facebook.com/sharer/sharer.php?u={{ $url }}"
        target="_blank" rel="noopener noreferrer"
        aria-label="{{ i18n "facebook" }}"
        class="btn-icon hover:text-accent hover:bg-surface transition-colors focus-visible:ring-2 focus-visible:ring-accent"
      >
        <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true" focusable="false">
          <path d="M18 2h-3a5 5 0 0 0-5 5v3H7v4h3v8h4v-8h3l1-4h-4V7a1 1 0 0 1 1-1h3z"/>
        </svg>
      </a>

      <!-- Twitter / X -->
      <a
        href="https://twitter.com/intent/tweet?url={{ $url }}&text={{ $title }}"
        target="_blank" rel="noopener noreferrer"
        aria-label="{{ i18n "twitter" }}"
        class="btn-icon hover:text-accent hover:bg-surface transition-colors focus-visible:ring-2 focus-visible:ring-accent"
      >
        <svg width="20" height="20" viewBox="0 0 24 24" fill="currentColor" stroke="none" aria-hidden="true" focusable="false">
          <path d="M18.244 2.25h3.308l-7.227 8.26 8.502 11.24H16.17l-5.214-6.817L4.99 21.75H1.68l7.73-8.835L1.254 2.25H8.08l4.713 6.231zm-1.161 17.52h1.833L7.084 4.126H5.117z"/>
        </svg>
      </a>

      <!-- Reddit -->
      <a
        href="https://www.reddit.com/submit?url={{ $url }}&title={{ $title }}"
        target="_blank" rel="noopener noreferrer"
        aria-label="{{ i18n "reddit" }}"
        class="btn-icon hover:text-accent hover:bg-surface transition-colors focus-visible:ring-2 focus-visible:ring-accent"
      >
        <svg width="20" height="20" viewBox="0 0 24 24" fill="currentColor" stroke="none" aria-hidden="true" focusable="false">
          <path d="M12 0A12 12 0 0 0 0 12a12 12 0 0 0 12 12 12 12 0 0 0 12-12A12 12 0 0 0 12 0zm5.01 4.744c.688 0 1.25.561 1.25 1.249a1.25 1.25 0 0 1-2.498.056l-2.597-.547-.8 3.747c1.824.07 3.48.632 4.674 1.488.308-.309.73-.491 1.207-.491.968 0 1.754.786 1.754 1.754 0 .716-.435 1.333-1.01 1.614a3.111 3.111 0 0 1 .042.52c0 2.694-3.13 4.87-7.004 4.87-3.874 0-7.004-2.176-7.004-4.87 0-.183.015-.366.043-.534A1.748 1.748 0 0 1 4.028 12c0-.968.786-1.754 1.754-1.754.463 0 .898.196 1.207.49 1.207-.883 2.878-1.43 4.744-1.487l.885-4.182a.342.342 0 0 1 .14-.197.35.35 0 0 1 .238-.042l2.906.617a1.214 1.214 0 0 1 1.108-.701zM9.25 12C8.561 12 8 12.562 8 13.25c0 .687.561 1.248 1.25 1.248.687 0 1.248-.561 1.248-1.249 0-.688-.561-1.249-1.249-1.249zm5.5 0c-.687 0-1.248.561-1.248 1.25 0 .687.561 1.248 1.249 1.248.688 0 1.249-.561 1.249-1.249 0-.687-.562-1.249-1.25-1.249zm-5.466 3.99a.327.327 0 0 0-.231.094.33.33 0 0 0 0 .463c.842.842 2.484.913 2.961.913.477 0 2.105-.056 2.961-.913a.361.361 0 0 0 .029-.463.33.33 0 0 0-.464 0c-.547.533-1.684.73-2.512.73-.828 0-1.979-.196-2.512-.73a.326.326 0 0 0-.232-.095z"/>
        </svg>
      </a>

      <!-- Pinterest -->
      <a
        href="https://pinterest.com/pin/create/button/?url={{ $url }}&description={{ $title }}"
        target="_blank" rel="noopener noreferrer"
        aria-label="{{ i18n "pinterest" }}"
        class="btn-icon hover:text-accent hover:bg-surface transition-colors focus-visible:ring-2 focus-visible:ring-accent"
      >
        <svg width="20" height="20" viewBox="0 0 24 24" fill="currentColor" stroke="none" aria-hidden="true" focusable="false">
          <path d="M12 0C5.373 0 0 5.373 0 12c0 5.084 3.163 9.426 7.627 11.174-.105-.949-.2-2.405.042-3.441.218-.937 1.407-5.965 1.407-5.965s-.359-.719-.359-1.782c0-1.668.967-2.914 2.171-2.914 1.023 0 1.518.769 1.518 1.69 0 1.029-.655 2.568-.994 3.995-.283 1.194.599 2.169 1.777 2.169 2.133 0 3.772-2.249 3.772-5.495 0-2.873-2.064-4.882-5.012-4.882-3.414 0-5.418 2.561-5.418 5.207 0 1.031.397 2.138.893 2.738a.36.36 0 0 1 .083.345l-.333 1.36c-.053.22-.174.267-.402.161-1.499-.698-2.436-2.889-2.436-4.649 0-3.785 2.75-7.262 7.929-7.262 4.163 0 7.398 2.967 7.398 6.931 0 4.136-2.607 7.464-6.227 7.464-1.216 0-2.359-.632-2.75-1.378l-.748 2.853c-.271 1.043-1.002 2.35-1.492 3.146C9.57 23.812 10.763 24 12 24c6.627 0 12-5.373 12-12S18.627 0 12 0z"/>
        </svg>
      </a>

      <!-- WhatsApp -->
      <a
        href="https://api.whatsapp.com/send?text={{ $title }}%20{{ $page.Permalink | urlquery }}"
        target="_blank" rel="noopener noreferrer"
        aria-label="{{ i18n "whatsapp" }}"
        class="btn-icon hover:text-accent hover:bg-surface transition-colors focus-visible:ring-2 focus-visible:ring-accent"
      >
        <svg width="20" height="20" viewBox="0 0 24 24" fill="currentColor" stroke="none" aria-hidden="true" focusable="false">
          <path d="M17.472 14.382c-.297-.149-1.758-.867-2.03-.967-.273-.099-.471-.148-.67.15-.197.297-.767.966-.94 1.164-.173.199-.347.223-.644.075-.297-.15-1.255-.463-2.39-1.475-.883-.788-1.48-1.761-1.653-2.059-.173-.297-.018-.458.13-.606.134-.133.298-.347.446-.52.149-.174.198-.298.298-.497.099-.198.05-.371-.025-.52-.075-.149-.669-1.612-.916-2.207-.242-.579-.487-.5-.669-.51-.173-.008-.371-.01-.57-.01-.198 0-.52.074-.792.372-.272.297-1.04 1.016-1.04 2.479 0 1.462 1.065 2.875 1.213 3.074.149.198 2.096 3.2 5.077 4.487.709.306 1.262.489 1.694.625.712.227 1.36.195 1.871.118.571-.085 1.758-.719 2.006-1.413.248-.694.248-1.289.173-1.413-.074-.124-.272-.198-.57-.347m-5.421 7.403h-.004a9.87 9.87 0 0 1-5.031-1.378l-.361-.214-3.741.982.998-3.648-.235-.374a9.86 9.86 0 0 1-1.51-5.26c.001-5.45 4.436-9.884 9.888-9.884 2.64 0 5.122 1.03 6.988 2.898a9.825 9.825 0 0 1 2.893 6.994c-.003 5.45-4.437 9.884-9.885 9.884m8.413-18.297A11.815 11.815 0 0 0 12.05 0C5.495 0 .16 5.335.157 11.892c0 2.096.547 4.142 1.588 5.945L.057 24l6.305-1.654a11.882 11.882 0 0 0 5.683 1.448h.005c6.554 0 11.89-5.335 11.893-11.893a11.821 11.821 0 0 0-3.48-8.413z"/>
        </svg>
      </a>

      <!-- Telegram -->
      <a
        href="https://t.me/share/url?url={{ $url }}&text={{ $title }}"
        target="_blank" rel="noopener noreferrer"
        aria-label="{{ i18n "telegram" }}"
        class="btn-icon hover:text-accent hover:bg-surface transition-colors focus-visible:ring-2 focus-visible:ring-accent"
      >
        <svg width="20" height="20" viewBox="0 0 24 24" fill="currentColor" stroke="none" aria-hidden="true" focusable="false">
          <path d="M11.944 0A12 12 0 0 0 0 12a12 12 0 0 0 12 12 12 12 0 0 0 12-12A12 12 0 0 0 12 0a12 12 0 0 0-.056 0zm4.962 7.224c.1-.002.321.023.465.14a.506.506 0 0 1 .171.325c.016.093.036.306.02.472-.18 1.898-.962 6.502-1.36 8.627-.168.9-.499 1.201-.82 1.23-.696.065-1.225-.46-1.9-.902-1.056-.693-1.653-1.124-2.678-1.8-1.185-.78-.417-1.21.258-1.91.177-.184 3.247-2.977 3.307-3.23.007-.032.014-.15-.056-.212s-.174-.041-.249-.024c-.106.024-1.793 1.14-5.061 3.345-.48.33-.913.49-1.302.48-.428-.008-1.252-.241-1.865-.44-.752-.245-1.349-.374-1.297-.789.027-.216.325-.437.893-.663 3.498-1.524 5.83-2.529 6.998-3.014 3.332-1.386 4.025-1.627 4.476-1.635z"/>
        </svg>
      </a>

      <!-- Signal -->
      <a
        href="https://signal.me/#p/{{ $page.Permalink | urlquery }}"
        target="_blank" rel="noopener noreferrer"
        aria-label="{{ i18n "signal" }}"
        class="btn-icon hover:text-accent hover:bg-surface transition-colors focus-visible:ring-2 focus-visible:ring-accent"
      >
        <svg width="20" height="20" viewBox="0 0 24 24" fill="currentColor" stroke="none" aria-hidden="true" focusable="false">
          <path d="M12 0C5.373 0 0 5.373 0 12s5.373 12 12 12 12-5.373 12-12S18.627 0 12 0zm.157 5.32a6.68 6.68 0 0 1 6.143 4.032l.734-.267.55 1.513-.717.261a6.71 6.71 0 0 1 .133 1.327 6.68 6.68 0 0 1-.176 1.51l.69.252-.55 1.513-.707-.258A6.68 6.68 0 0 1 12 18.68a6.68 6.68 0 0 1-6.294-4.455l-.66.24-.55-1.513.677-.247A6.71 6.71 0 0 1 5 12.187a6.71 6.71 0 0 1 .16-1.438l-.698-.254.55-1.513.725.264A6.68 6.68 0 0 1 12.157 5.32zM12 7.2a4.8 4.8 0 1 0 0 9.6A4.8 4.8 0 0 0 12 7.2z"/>
        </svg>
      </a>

    </div>
  </nav>
</div>
```

- [ ] **Step 2: Verify Hugo builds cleanly**

```bash
hugo -D 2>&1 | tail -10
```

Expected: build completes, no errors. Page count unchanged (partial not yet included anywhere).

- [ ] **Step 3: Commit**

```bash
git add themes/danix-xyz-hacker/layouts/partials/social-share.html
git commit -m "feat: add social-share partial with 9 targets and two layout modes"
```

---

## Task 3: Wire into Sidebar

**Files:**
- Modify: `themes/danix-xyz-hacker/layouts/partials/sidebar.html`

Current sidebar structure:
- Lines 1–8: Author widget
- Lines 10–42: Related posts widget (articles only)

- [ ] **Step 1: Insert the partial call after the author widget**

In `themes/danix-xyz-hacker/layouts/partials/sidebar.html`, insert the call between the closing `</div>` of the author widget (line 8) and the related posts comment (line 10):

```html
<aside class="order-last md:order-none md:col-span-1">
  <!-- Author info widget (optional - can be expanded) -->
  <div class="p-4 border border-border/30 rounded mb-6">
    <h3 class="text-lg font-semibold text-accent mb-3">{{ i18n "author" }}</h3>
    <p class="text-text-dim text-sm leading-relaxed">
      {{ .Site.Params.author }}
    </p>
  </div>

  <!-- Social sharing widget -->
  {{ partial "social-share.html" (dict "page" . "mode" "sidebar") }}

  <!-- Related posts widget (articles only) -->
  {{ if and .Site.Params.relatedPosts (eq .Type "articles") }}
  ...
```

- [ ] **Step 2: Build and verify sidebar renders on an article**

```bash
hugo -D 2>&1 | tail -5
```

Then open an article page in the built `public/` directory and verify the widget is present:

```bash
grep -A 5 "share" public/articles/git-setup-own-server/index.html | head -20
```

Expected: HTML contains the `<nav aria-label=` share widget with button elements.

- [ ] **Step 3: Verify widget also appears on a page (not just articles)**

```bash
grep -c "btn-icon" public/is/index.html
```

Expected: at least 9 (one per share button).

- [ ] **Step 4: Commit**

```bash
git add themes/danix-xyz-hacker/layouts/partials/sidebar.html
git commit -m "feat: add social sharing widget to sidebar (articles and pages)"
```

---

## Task 4: Wire into Repository Page (Inline Mode)

**Files:**
- Modify: `themes/danix-xyz-hacker/layouts/repository/list.html`

Current structure relevant lines:
- Line 15: `<div class="prose dark:prose-invert max-w-none mb-12">{{ .Content }}</div>`
- Line 20: `<section class="mt-16">` (cards grid)

- [ ] **Step 1: Insert the inline partial call after `.Content` block**

Replace the prose block and following section in `themes/danix-xyz-hacker/layouts/repository/list.html`:

```html
    <!-- Page Content (markdown sections) -->
    <div class="prose dark:prose-invert max-w-none mb-12">
      {{ .Content }}
    </div>

    <!-- Social sharing (inline mode) -->
    <div class="mb-12">
      {{ partial "social-share.html" (dict "page" . "mode" "inline") }}
    </div>

    <!-- Repository Cards Section -->
    <section class="mt-16">
```

- [ ] **Step 2: Build and verify repository page contains the inline widget**

```bash
hugo -D 2>&1 | tail -5
grep -c "btn-icon" public/repository/index.html
```

Expected: at least 9 matches (one per share button).

- [ ] **Step 3: Verify grid class is inline (5-col)**

```bash
grep "grid-cols-5" public/repository/index.html
```

Expected: one match — `grid grid-cols-5 gap-3 justify-items-center`.

- [ ] **Step 4: Commit**

```bash
git add themes/danix-xyz-hacker/layouts/repository/list.html
git commit -m "feat: embed social sharing widget inline on repository page"
```

---

## Task 5: CSS Rebuild and Final Verification

**Files:**
- Run: `npm run build` (compiles `main.css` → `main.min.css`)

The new classes used (`grid-cols-5`, `justify-items-center`, `focus-visible:ring-2`, `focus-visible:ring-accent`, `text-accent2`) need to be compiled into the CSS bundle. All are Tailwind utilities — they just need to appear in template files for Tailwind's content scanner to pick them up.

- [ ] **Step 1: Rebuild CSS**

```bash
npm run build 2>&1 | tail -5
```

Expected: exits with no errors, `themes/danix-xyz-hacker/assets/css/main.min.css` is updated.

- [ ] **Step 2: Full build check**

```bash
hugo -D 2>&1 | tail -10
```

Expected: clean build, same page counts as before.

- [ ] **Step 3: Spot-check rendered output — sidebar mode**

```bash
grep -A 3 "grid-cols-2" public/articles/git-setup-own-server/index.html | head -10
```

Expected: `<div class="grid grid-cols-2 gap-2">` present.

- [ ] **Step 4: Spot-check rendered output — inline mode**

```bash
grep -A 3 "grid-cols-5" public/repository/index.html | head -10
```

Expected: `<div class="grid grid-cols-5 gap-3 justify-items-center">` present.

- [ ] **Step 5: Spot-check copy button Alpine.js attributes**

```bash
grep -A 10 "x-data.*copied" public/articles/git-setup-own-server/index.html | head -15
```

Expected: `x-data="{ copied: false }"` with `@click` containing `navigator.clipboard.writeText` and the article's full permalink URL.

- [ ] **Step 6: Spot-check Twitter URL includes title and permalink**

```bash
grep "twitter.com/intent" public/articles/git-setup-own-server/index.html
```

Expected: URL contains both `url=` and `text=` query parameters with URL-encoded values.

- [ ] **Step 7: Spot-check Italian translation**

```bash
grep "Condividi" public/it/articles/git-setup-own-server/index.html | head -5
```

Expected: `aria-label="Condividi"` on the `<nav>` element.

- [ ] **Step 8: Final commit**

```bash
git add themes/danix-xyz-hacker/assets/css/main.min.css
git commit -m "build: rebuild CSS to include social sharing widget utility classes"
```