From 19e1c80e154739e4b61385301e55aed97c8eb90f Mon Sep 17 00:00:00 2001 From: "Danilo M." Date: Fri, 26 Jun 2026 16:59:23 +0200 Subject: docs: add Slackware projects section implementation plan Co-Authored-By: Claude Opus 4.8 --- .../plans/2026-06-26-slackware-projects-section.md | 778 +++++++++++++++++++++ 1 file changed, 778 insertions(+) create mode 100644 docs/superpowers/plans/2026-06-26-slackware-projects-section.md (limited to 'docs/superpowers/plans/2026-06-26-slackware-projects-section.md') diff --git a/docs/superpowers/plans/2026-06-26-slackware-projects-section.md b/docs/superpowers/plans/2026-06-26-slackware-projects-section.md new file mode 100644 index 0000000..8213367 --- /dev/null +++ b/docs/superpowers/plans/2026-06-26-slackware-projects-section.md @@ -0,0 +1,778 @@ +# Slackware Projects Section 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 `slackware` Hugo section with a clickable hub page that aggregates per-project deep-dive pages (styled rows), restructure the main menu (rename two entries, add nested "Slackware" parent with desktop hover + mobile indented submenu), reuse the shared `tags` taxonomy for project tech, and index projects in site search. + +**Architecture:** New Hugo section `content/{en,it}/slackware/` with `_index.md` (hub) and `/index.md` pages. Hub list layout loops project pages into full-width alternating rows (option #3 shape, #2 styling). Project single layout reuses the `repository/single.html` shell plus a project-header partial. Menu nesting via `parent =` in `hugo.toml`; desktop submenu is CSS-only (`group-hover` + `group-focus-within`), mobile shows indented children. Tech tags use the existing `tags` taxonomy. + +**Tech Stack:** Hugo (extended), Tailwind CSS (npm build → `main.min.css`), Alpine.js (existing, unchanged here), Hugo i18n YAML. + +**Verification model:** No unit-test runner exists for templates. Each task verifies with `hugo` build/render checks (build succeeds, expected HTML/text present in output) and ends with a commit. Theme files commit inside the `themes/danix-xyz-hacker/` submodule; content/config/i18n commit in the content repo, per CLAUDE.md Git workflow. + +**Pre-flight (run once before Task 1):** +- Content repo root: `/home/danix/Programming/GIT/danix.xyz-hacker-theme` +- Confirm theme submodule is on master: `cd themes/danix-xyz-hacker && git checkout master && cd ../..` +- All `hugo` build checks below run from the content repo root. + +--- + +### Task 1: Scaffold the slackware section content (EN + IT) + +Creates the section so later layout work has real pages to render. Includes one sample project used by every later render check. + +**Files:** +- Create: `content/en/slackware/_index.md` +- Create: `content/it/slackware/_index.md` +- Create: `content/en/slackware/sample-project/index.md` +- Create: `content/it/slackware/sample-project/index.md` + +- [ ] **Step 1: Create EN hub index** + +`content/en/slackware/_index.md`: +```toml ++++ +title = "Slackware" +date = 2026-06-26T00:00:00Z ++++ + +I build and run everything on **Slackware**. This page collects the projects +I maintain around it, and the reasons I keep choosing it: simplicity, +transparency, and staying out of my way. +``` + +- [ ] **Step 2: Create IT hub index** + +`content/it/slackware/_index.md`: +```toml ++++ +title = "Slackware" +date = 2026-06-26T00:00:00Z ++++ + +Costruisco e uso tutto su **Slackware**. Questa pagina raccoglie i progetti +che mantengo intorno ad essa, e i motivi per cui continuo a sceglierla: +semplicità, trasparenza, e non mettersi in mezzo. +``` + +- [ ] **Step 3: Create EN sample project** + +`content/en/slackware/sample-project/index.md`: +```toml ++++ +title = "Sample Project" +tagline = "A placeholder project to validate the section layout." +status = "active" +repo_url = "https://git.danix.xyz/sample-project" +tags = ["bash", "slackbuild", "python"] ++++ + +## What it is + +Freeform body content for the sample project. + +## How it works + +Details here. + +## Rationale + +Why it exists. +``` + +- [ ] **Step 4: Create IT sample project** + +`content/it/slackware/sample-project/index.md`: +```toml ++++ +title = "Progetto di Esempio" +tagline = "Un progetto segnaposto per validare il layout della sezione." +status = "active" +repo_url = "https://git.danix.xyz/sample-project" +tags = ["bash", "slackbuild", "python"] ++++ + +## Cos'è + +Contenuto libero per il progetto di esempio. + +## Come funziona + +Dettagli qui. + +## Motivazione + +Perché esiste. +``` + +- [ ] **Step 5: Verify build succeeds and pages exist** + +Run: `hugo --quiet && ls public/en/slackware/sample-project/index.html public/it/slackware/sample-project/index.html` +Expected: build completes with no errors; both files listed. (Pages render with Hugo's default `_default` layouts for now — that's fine; dedicated layouts come in Tasks 5–6.) + +- [ ] **Step 6: Commit (content repo)** + +```bash +git add content/en/slackware content/it/slackware +git commit -m "feat: scaffold slackware projects section (EN/IT) with sample project" +``` + +--- + +### Task 2: Add i18n keys and rename menu labels + +Renames "Git Repository"→Projects and "Repo"→Packages via i18n values (menu labels render through `i18n .Name`), and adds all new keys the later layouts need. + +**Files:** +- Modify: `i18n/en.yaml` +- Modify: `i18n/it.yaml` + +- [ ] **Step 1: Rename + add EN keys** + +In `i18n/en.yaml`, change the existing values: +```yaml +gitrepo: "Projects" +repo: "Packages" +``` +Then add these new keys (anywhere in the file): +```yaml +slackware: "Slackware" +slackwareTitle: "Slackware" +slackwareSubtitle: "Projects I build and maintain on Slackware." +projectStatus: "Status" +viewRepo: "View repository" +status-active: "active" +status-maintained: "maintained" +status-wip: "wip" +status-archived: "archived" +``` + +- [ ] **Step 2: Rename + add IT keys** + +In `i18n/it.yaml`, change the existing values: +```yaml +gitrepo: "Progetti" +repo: "Pacchetti" +``` +Then add: +```yaml +slackware: "Slackware" +slackwareTitle: "Slackware" +slackwareSubtitle: "Progetti che costruisco e mantengo su Slackware." +projectStatus: "Stato" +viewRepo: "Vedi repository" +status-active: "attivo" +status-maintained: "mantenuto" +status-wip: "in corso" +status-archived: "archiviato" +``` + +- [ ] **Step 3: Verify build + label rendering** + +Run: `hugo --quiet && grep -o "Projects\|Packages" public/en/index.html | sort -u` +Expected: build succeeds; output contains both `Projects` and `Packages` (the renamed desktop menu labels). + +- [ ] **Step 4: Commit (content repo)** + +```bash +git add i18n/en.yaml i18n/it.yaml +git commit -m "feat: rename menu labels (Projects/Packages) and add slackware i18n keys" +``` + +--- + +### Task 3: Restructure menu config (nest Packages + Slackware hub) + +Adds the Slackware parent (→ hub) and nests Packages under it, in both language menus. Keeps Projects external. + +**Files:** +- Modify: `hugo.toml` (Italian menu block ~lines 76–94; English menu block ~lines 122–140) + +- [ ] **Step 1: Add Slackware parent + nest repository (IT)** + +In `hugo.toml`, in the `languages.it.menus.main` block: leave the `gitrepo` (external) entry as-is. Replace the existing `repository` entry with a new Slackware parent plus the nested Packages entry: + +```toml + [[languages.it.menus.main]] + identifier = "slackware" + pageRef = "/slackware" + name = "slackware" + weight = 5 + + [[languages.it.menus.main]] + identifier = "repository" + pageRef = "/repository" + name = "repo" + parent = "slackware" + weight = 1 +``` +(Leave the `legal` entry at weight 6.) + +- [ ] **Step 2: Add Slackware parent + nest repository (EN)** + +In the `languages.en.menus.main` block, make the identical change: + +```toml + [[languages.en.menus.main]] + identifier = "slackware" + pageRef = "/slackware" + name = "slackware" + weight = 5 + + [[languages.en.menus.main]] + identifier = "repository" + pageRef = "/repository" + name = "repo" + parent = "slackware" + weight = 1 +``` + +- [ ] **Step 2b: Add project pages into the submenu (both languages)** + +Hugo does not auto-add section pages to a menu. To make project pages appear in the Slackware submenu, add `menu` front-matter to each project. Update both sample project files from Task 1 by adding to their front-matter: + +`content/en/slackware/sample-project/index.md` and `content/it/slackware/sample-project/index.md`, add inside the `+++`: +```toml +[menus.main] + parent = "slackware" + weight = 10 +``` + +- [ ] **Step 3: Verify menu nesting** + +Run: `hugo --quiet && hugo list all >/dev/null 2>&1; echo "build ok"` +Then confirm the parent renders without breaking the existing top-level menu: `grep -c "Slackware" public/en/index.html` +Expected: build ok; count >= 1. (Submenu HTML wiring is added in Tasks 4 & 7; here we only assert config builds and the parent label appears.) + +- [ ] **Step 4: Commit (content repo)** + +```bash +git add hugo.toml content/en/slackware/sample-project/index.md content/it/slackware/sample-project/index.md +git commit -m "feat: nest Packages under new Slackware menu parent (both languages)" +``` + +--- + +### Task 4: Desktop header submenu (CSS-only hover + focus-within) + +Makes the desktop nav render children as a centered row below the bar on hover/focus, for any menu item that has children. Items without children are unchanged. + +**Files:** +- Modify: `themes/danix-xyz-hacker/layouts/partials/header.html:13-27` + +- [ ] **Step 1: Replace the desktop menu loop** + +In `header.html`, replace the desktop menu block (the `` containing the `range .Site.Menus.main`) with a parent-aware version: + +```html + + +``` + +Note: this also fixes the pre-existing bug where external top-level items (Projects) rendered `i18n .Name` and lacked `target="_blank"` in the desktop bar. Now external items use `.Name` + new tab, matching the overlay. + +- [ ] **Step 2: Verify submenu HTML renders** + +Run: `hugo --quiet && grep -o "group-hover:flex" public/en/index.html | head -1` +Expected: build succeeds; `group-hover:flex` present (submenu wrapper emitted). Also confirm Packages link is inside: `grep -A30 "aria-haspopup" public/en/index.html | grep -c "/en/repository/"` → >= 1. + +- [ ] **Step 3: Commit (theme submodule)** + +```bash +cd themes/danix-xyz-hacker +git add layouts/partials/header.html +git commit -m "feat: desktop nav submenu for nested menu items (CSS hover + focus-within)" +git push origin master +cd ../.. +``` + +--- + +### Task 5: Project header partial + +Renders the light-schema header (tagline, status badge, repo link, optional image, tech pills) above project body. Used by the single layout (Task 6). + +**Files:** +- Create: `themes/danix-xyz-hacker/layouts/partials/project-header.html` + +- [ ] **Step 1: Write the partial** + +`themes/danix-xyz-hacker/layouts/partials/project-header.html`: +```html +{{ $status := .Params.status | default "active" }} +{{ $statusColor := "var(--color-accent, #a855f7)" }} +{{ if eq $status "maintained" }}{{ $statusColor = .Site.Params.secondaryAccent }}{{ end }} +{{ if eq $status "wip" }}{{ $statusColor = "#f59e0b" }}{{ end }} +{{ if eq $status "archived" }}{{ $statusColor = "#9ca3af" }}{{ end }} + +{{ $imageURL := "" }} +{{ if .Params.image }} + {{ $res := .Resources.GetMatch .Params.image }} + {{ if $res }}{{ $imageURL = $res.RelPermalink }}{{ else }}{{ $imageURL = .Params.image }}{{ end }} +{{ end }} + +
+ {{ if $imageURL }} + {{ .Title }} + {{ end }} + +
+

{{ .Title }}

+ + {{ i18n (printf "status-%s" $status) }} + +
+ + {{ with .Params.tagline }} +

{{ . }}

+ {{ end }} + +
+ {{ with .Params.repo_url }} + + {{ i18n "viewRepo" }} + + + {{ end }} + {{ with .Params.tags }} +
    + {{ range . }} +
  • {{ . }}
    • + {{ end }} +
+ {{ end }} +
+
+``` + +- [ ] **Step 2: Commit (theme submodule)** + +(Partial is rendered by Task 6's layout; verification happens there. Commit now to keep tasks atomic.) +```bash +cd themes/danix-xyz-hacker +git add layouts/partials/project-header.html +git commit -m "feat: add project-header partial (status badge, repo link, tech pills)" +git push origin master +cd ../.. +``` + +--- + +### Task 6: Project single layout + +Wires `project-header.html` above the freeform body, reusing the `repository/single.html` shell idiom (breadcrumb, content-grid, prose, social-share). + +**Files:** +- Create: `themes/danix-xyz-hacker/layouts/slackware/single.html` + +- [ ] **Step 1: Write the single layout** + +`themes/danix-xyz-hacker/layouts/slackware/single.html`: +```html +{{ define "main" }} +
+
+ {{ partial "breadcrumb.html" . }} + + {{ partial "project-header.html" . }} + +
+ {{ .Content }} +
+ +
+ {{ partial "social-share.html" (dict "page" . "mode" "inline") }} +
+
+
+{{ end }} +``` + +- [ ] **Step 2: Verify project page renders header + body** + +Run: `hugo --quiet && grep -o "status-active\|active" public/en/slackware/sample-project/index.html | head -1 && grep -c "View repository" public/en/slackware/sample-project/index.html` +Expected: build succeeds; the status badge text (`active`) present; `View repository` count >= 1. Also `grep -c "What it is" public/en/slackware/sample-project/index.html` → >= 1 (freeform body rendered). + +- [ ] **Step 3: Commit (theme submodule)** + +```bash +cd themes/danix-xyz-hacker +git add layouts/slackware/single.html +git commit -m "feat: slackware project single layout with project header" +git push origin master +cd ../.. +``` + +--- + +### Task 7: Mobile overlay indented children + +Renders child links indented under their parent in the hamburger overlay. Items without children unchanged. + +**Files:** +- Modify: `themes/danix-xyz-hacker/layouts/partials/hamburger-menu.html:30-45` + +- [ ] **Step 1: Replace the overlay menu loop** + +In `hamburger-menu.html`, replace the `{{ range .Site.Menus.main }}…{{ end }}` block inside `