# 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.