From ad032a08b800961997a33880e9ab9e6234a253b9 Mon Sep 17 00:00:00 2001
From: "Danilo M." <danix@danix.xyz>
Date: Fri, 26 Jun 2026 16:56:30 +0200
Subject: docs: add Slackware projects section design spec

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 ...2026-06-26-slackware-projects-section-design.md | 206 +++++++++++++++++++++
 1 file changed, 206 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-06-26-slackware-projects-section-design.md

(limited to 'docs')

diff --git a/docs/superpowers/specs/2026-06-26-slackware-projects-section-design.md b/docs/superpowers/specs/2026-06-26-slackware-projects-section-design.md
new file mode 100644
index 0000000..eed2061
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-26-slackware-projects-section-design.md
@@ -0,0 +1,206 @@
+# Slackware Projects Section — Design
+
+Date: 2026-06-26
+Status: approved (pending written-spec review)
+
+## Goal
+
+Give each Slackware-centric project a long-lived, official reference page (not
+a dated blog post): what it is, how it works, the rationale. Aggregate these
+under a new "Slackware" hub page that also explains why Danilo uses Slackware.
+Restructure the main menu to introduce the hub.
+
+## Scope
+
+In scope:
+- New `slackware` Hugo section (EN + IT), one page per project via folder drop.
+- Slackware landing/hub page (clickable) that lists project pages as styled rows.
+- Light front-matter schema + per-project header partial.
+- Menu restructure: rename two entries, add "Slackware" parent with a desktop
+  hover submenu and a mobile indented sub-list.
+- Project tech tags reuse the existing shared `tags` taxonomy.
+- Extend site search index to include the `slackware` section.
+
+Out of scope (YAGNI):
+- Live git/cgit status fetching (status is a front-matter string).
+- A second/standalone desktop nav system (we extend the existing one).
+- Tag filtering UI on the hub (taxonomy term pages already aggregate).
+
+## Menu restructure
+
+Current main menu: Articles, About, Contact, Git Repository (→git.danix.xyz,
+external), Repo (→/repository), Privacy.
+
+Target:
+- Articles — unchanged
+- About — unchanged
+- Contact — unchanged
+- **Projects** — renamed from "Git Repository". Still → https://git.danix.xyz/,
+  keeps `external = true` (external glyph + new tab).
+- **Slackware** — NEW. Clickable → `/slackware/` landing page. Parent of:
+  - **Packages** — renamed from "Repo". → internal `/repository` page. NO
+    external glyph (it's an internal Hugo page). Nested under Slackware.
+  - (each project page also appears in the submenu)
+- Privacy — unchanged
+
+Implemented in `hugo.toml` via Hugo menu nesting: child entries get
+`parent = "slackware"`. Both `languages.it.menus.main` and
+`languages.en.menus.main` updated symmetrically.
+
+### Desktop submenu (header.html)
+
+The desktop nav (`hidden md:flex`) gets nesting for items that have
+`.Children`:
+- Wrap the parent item in a `group relative` container.
+- Parent link → landing page (`/slackware/`).
+- Submenu: a row of links, `hidden group-hover:flex group-focus-within:flex`,
+  absolutely positioned, centered, full-width-ish below the bar. A small
+  padding "bridge" prevents hover flicker in the gap between row and submenu.
+- A11y: `group-focus-within:flex` reveals the submenu on keyboard Tab as well
+  as mouse hover. Parent gets `aria-haspopup="true"`; submenu container is a
+  `<ul>` with appropriate roles.
+- Styling: frosted/`bg` panel matching the existing `frosted-bar`, accent
+  hover on links, oxanium nowhere new — links match existing desktop link
+  styling.
+
+Items without children render exactly as today (no behavior change).
+
+### Mobile submenu (hamburger-menu.html)
+
+Flat `range .Site.Menus.main` becomes parent-aware:
+- Parent renders as a link (to landing page).
+- If `.HasChildren`, child links render indented beneath it (left padding +
+  thin accent left border), always visible (no JS accordion — KISS, the list
+  is short).
+- Children inherit the existing overlay link styling.
+
+## Content model
+
+### Section layout
+
+```
+content/en/slackware/_index.md          # hub landing (EN)
+content/en/slackware/<project>/index.md  # one project (EN)
+content/it/slackware/_index.md           # hub landing (IT)
+content/it/slackware/<project>/index.md  # one project (IT)
+```
+
+Adding a project = drop a folder with `index.md`. It appears on the hub
+automatically (section list) and in menus if desired.
+
+### Project front-matter (light schema)
+
+```toml
++++
+title    = "Project Name"
+tagline  = "One-line what-and-why."
+status   = "active"           # active | maintained | wip | archived
+repo_url = "https://git.danix.xyz/project"   # optional
+image    = "logo.png"         # optional page resource; mono-glyph fallback
+tags     = ["bash", "slackbuild", "python"]  # shared taxonomy + tech pills
++++
+
+Freeform markdown body. Any headings/shortcodes.
+```
+
+- `status` → colored badge. Color map (reuse palette):
+  - active → accent purple
+  - maintained → `secondaryAccent` (#00ff88)
+  - wip → amber/warning
+  - archived → muted `text-dim`
+- `image` resolved as a page resource (like `article-card.html` does);
+  fallback = a generated mono-glyph block (first letters on an accent panel)
+  when absent.
+- `tags` feed BOTH the rendered tech pills and Hugo's global `tags` taxonomy,
+  so `/tags/python/` aggregates articles + projects with no extra code.
+
+### Project single page (`layouts/slackware/single.html`)
+
+Mirrors `repository/single.html` shell (breadcrumb, content-grid, prose,
+social-share). Adds a **project header partial** above the body rendering:
+tagline, status badge, repo link (with external glyph), optional image,
+tech pills. Body = freeform `.Content`.
+
+New partial: `layouts/partials/project-header.html`.
+
+## Hub landing page (`layouts/slackware/list.html`)
+
+- Top: hero title + subtitle (i18n) + the `_index.md` freeform body (the "why
+  Slackware" prose, project overview).
+- Then: project rows — **shape of option #3, styling of option #2**:
+  - Full-width horizontal rows, stacked, one per project.
+  - Alternating image side left/right for rhythm (`:nth-child` / loop index).
+  - Each row: accent left-border stripe, project image (or mono-glyph block)
+    on one side; on the other: oxanium title, status badge (top-right),
+    tagline, tech pills row, CTA ("Read more →" + repo link if present).
+  - Hover: accent border glow + slight lift (`transition`, `hover:-translate-y`).
+  - No terminal mimicry.
+- New partial: `layouts/partials/project-row.html` (one row), looped by
+  `list.html` over `.Pages`.
+- Packages: the hub body links to `/repository` (Packages) as the
+  canonical package-repo page; it is also reachable via the submenu.
+
+## Search index
+
+`layouts/index.json` currently indexes only `Section == "articles"`. Extend to
+also include `Section == "slackware"` so the search box returns projects.
+Project entries use title / url / date / summary like articles. ~3-line change
+(union the two page sets before ranging).
+
+## i18n
+
+New keys in BOTH `i18n/en.yaml` and `i18n/it.yaml`:
+- Menu: `slackware`, `projects` (Projects), `packages` (Packages).
+- Hub: `slackwareTitle`, `slackwareSubtitle`.
+- Project header / rows: `projectStatus`, `viewRepo`, `status-active`,
+  `status-maintained`, `status-wip`, `status-archived`, `readMore` (exists).
+
+External menu names (Projects → git.danix.xyz) follow the existing pattern
+where external items use `.Name` literally; internal items use `i18n .Name`.
+Projects is external, so its label is set per-language in `hugo.toml` menu
+config (matching how the current external "Git Repository" entry works).
+
+## CSS
+
+New Tailwind utility/component classes (project rows, status badges, tech
+pills, submenu panel). Built via `npm run build` → `main.min.css`, committed
+inside the theme submodule per the project Git workflow. Prefer `@apply`
+semantic components consistent with the existing card/callout styles.
+
+## New / changed files
+
+New:
+- `content/{en,it}/slackware/_index.md`
+- `themes/.../layouts/slackware/list.html`
+- `themes/.../layouts/slackware/single.html`
+- `themes/.../layouts/partials/project-header.html`
+- `themes/.../layouts/partials/project-row.html`
+
+Changed:
+- `hugo.toml` (menu restructure: rename + nested entries, both languages)
+- `themes/.../layouts/partials/header.html` (desktop hover submenu)
+- `themes/.../layouts/partials/hamburger-menu.html` (mobile indented children)
+- `themes/.../layouts/index.json` (index slackware section)
+- `i18n/en.yaml`, `i18n/it.yaml` (new keys)
+- `themes/.../assets/css/main.css` → rebuilt `main.min.css`
+- `SHORTCODES.md` only if a new shortcode is added (none planned).
+
+## Testing / verification
+
+- `hugo server` builds without errors; `/en/slackware/` and `/it/slackware/`
+  render hub + rows; a sample project page renders header + body.
+- Desktop: hover and keyboard-Tab both reveal the Slackware submenu; links
+  resolve; Projects opens git.danix.xyz in a new tab with glyph.
+- Mobile overlay: Slackware shows indented children; links navigate.
+- `/tags/<tech>/` lists the sample project alongside any article with that tag.
+- Search box returns the sample project by title/summary term.
+- Both languages symmetric; no missing i18n keys (no raw key strings in UI).
+
+## Decisions captured
+
+- Status is a front-matter string (badge), not live git fetch. (flaky/CORS path
+  rejected.)
+- Tech tags reuse the shared `tags` taxonomy (unified term pages + search),
+  not a separate parallel field. Namespace is intentionally shared.
+- Hover submenu is CSS-only (no Alpine), with focus-within for a11y.
+- Hub rows: option #3 shape + option #2 styling, no terminal aesthetic.
-- 
cgit v1.2.3