Merge pull request #14 from NC3-LU/codex_hugoFix

SteveClement · web-flow · commit bfbe0f6e41f0 · 2025-11-06T02:43:00.000+09:00
fix: [hugo] hugo fix
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,44 @@
+# Repository Guidelines
+
+Use this guide when contributing to Code @ LHC's Hugo site to keep content consistent and builds reliable.
+
+## Project Structure & Module Organization
+- `content/` houses Markdown with TOML front matter; subfolders mirror site navigation and service areas. Prefer Hugo shortcodes (e.g. `readme`) over raw HTML embeds.
+- `layouts/` and `layouts/shortcodes/` override theme templates; keep page partials grouped by section to avoid collisions.
+- `assets/sass/` contains the SCSS processed by Hugo Extended; rely on the Hugo Pipes pipeline instead of committing compiled CSS.
+- `static/` serves images and downloads verbatim; store heavy media externally and link here only when needed.
+- `data/` exposes YAML/TOML snippets consumed by shortcodes, ideal for project inventories and shared content blocks.
+- `themes/kode` (active) and `themes/hugo-arcana` are git submodules; sync them before editing and avoid direct changes without upstream pull requests.
+- `public/` is generated build output; never edit it manually.
+
+## Build, Test, and Development Commands
+- `git submodule update --init --recursive` ensures theme sources are available after cloning or switching branches.
+- `hugo server -D --disableFastRender` runs a local preview with drafts enabled and reloads assets on each request (http://localhost:1313).
+- `hugo --cleanDestinationDir --gc --minify` mirrors the CI build, prunes unused assets, and writes fresh output to `public/`; run before pushing.
+- `hugo --panicOnWarning` catches missing resources, shortcode errors, or front matter issues during review.
+- `npm ci` (optional) installs theme tooling when a `package-lock.json` is introduced or updated.
+
+## Coding Style & Naming Conventions
+- Follow `.editorconfig`: 4-space indentation by default, 2 spaces for HTML/CSS/JS/YAML, tabs only in `Makefile`; always keep UTF-8 with LF endings and a trailing newline.
+- Author content in Markdown with TOML front matter; wrap prose near 100 characters and prefer semantic Markdown (lists, tables) over ad-hoc HTML.
+- Name new content files in `kebab-case.md`; include standard fields like `title`, `author`, `description`, `repository`, `weight`, and `draft`. Legacy files may differ—match nearby conventions when touching existing content.
+- Keep SCSS indented with two spaces and organized by component; do not commit generated CSS.
+- Place reusable snippets in `layouts/shortcodes/` instead of embedding raw HTML directly in content files.
+
+## Testing Guidelines
+- Toggle `draft = true` while iterating on new pages, flipping to `false` only when ready to publish.
+- Verify new or updated pages via `hugo server` and watch the terminal/browser console for warnings about missing resources or broken links.
+- Run `hugo --cleanDestinationDir --gc --minify` locally and spot-check `public/index.html` (or affected pages) for layout regressions.
+- Use `hugo --panicOnWarning` to fail fast on front matter or shortcode issues.
+- After Sass changes, confirm compiled styles in the browser and resolve any console warnings.
+- The repository has no automated unit tests; document manual verification steps in pull requests.
+
+## Commit & Pull Request Guidelines
+- Follow the existing `type: [scope] message` pattern (e.g. `new: [project] Add Range42`) using imperative verbs.
+- Group related changes per commit, separating content edits from theme updates to ease review.
+- Pull requests should link related issues, describe the change, list manual checks (commands run), and attach screenshots or GIFs for UI adjustments.
+- Confirm `hugo --cleanDestinationDir --minify` (and other relevant checks) passes before requesting review.
+
+## Security & Configuration Tips
+- Global settings live in `config/_default/`; review `params.toml` before introducing site-wide toggles.
+- The default `theme_kode` branch deploys via `.github/workflows/hugo.yml`; keep the pinned Hugo Extended (0.108.0) and Dart Sass versions updated together when bumping.
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,120 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+Code @ LHC is a Hugo-based static site showcasing open source cybersecurity projects from the Luxembourg House of Cybersecurity (LHC), including projects from CIRCL and NC3. The site is deployed automatically to GitHub Pages when pushing to the `theme_kode` branch.
+
+## Essential Commands
+
+### Setup
+```bash
+# Clone with theme submodules
+git submodule update --init --recursive
+
+# Install optional Node.js dependencies (if needed by theme)
+npm ci
+```
+
+### Development
+```bash
+# Run local dev server with drafts enabled
+hugo server -D --disableFastRender
+
+# Access at http://localhost:1313
+```
+
+### Build & Testing
+```bash
+# Production build (matches CI pipeline)
+hugo --cleanDestinationDir --gc --minify
+
+# Build with strict error checking
+hugo --panicOnWarning
+```
+
+## Architecture
+
+### Content Management
+- **Project pages**: Each project is a Markdown file in `content/projects/` with TOML front matter
+- **Dynamic README fetching**: The `{{< readme >}}` shortcode (`layouts/shortcodes/readme.html`) fetches and renders the project's README.md directly from GitHub using the `repository` front matter field
+- **Homepage configuration**: `data/homepage.yml` controls the homepage layout and content sections
+
+### Required Front Matter for Projects
+```toml
++++
+title = "Project Name"
+author = "CIRCL" # or "NC3"
+description = "Brief description"
+logo = "logo-project.png"  # Must exist in static/img/
+weight = 10  # Controls display order
+draft = false
+repository = "org/repo"  # GitHub repo path for {{< readme >}} shortcode
+tags = ["projects", "tag1", "tag2"]
++++
+```
+
+### Theme System
+- Primary theme: `kode` (located in `themes/kode/`)
+- Themes are **git submodules** - always sync before editing theme assets
+- Override theme templates by placing files in root `layouts/` directory
+- Custom shortcodes: `layouts/shortcodes/` (readme.html, osm.html, rawhtml.html)
+
+### Static Assets
+- `static/img/` - Project logos and images (served as-is)
+- `static/images/` - Banner and site images
+- `assets/sass/` - Source styles (processed by Hugo's asset pipeline)
+- `public/` - Generated build output (never edit manually, excluded from git)
+
+### Configuration
+- `config.toml` - Main Hugo configuration
+  - Base URL: https://code.lhc.lu
+  - Theme: kode
+  - Hugo version used in CI: 0.108.0 (specified in `.github/workflows/hugo.yml`)
+  - Social links and menu configuration
+
+## Code Style (from .editorconfig)
+
+- **Default**: 4-space indentation
+- **HTML/CSS/JS/YAML**: 2-space indentation
+- **Makefiles**: Tab indentation
+- **Encoding**: UTF-8 with LF line endings
+- **Markdown**: May retain intentional double trailing spaces (for line breaks)
+- Always include trailing newline
+
+## Commit Message Format
+
+Follow existing pattern: `type: [scope] message`
+
+Examples:
+- `new: [project] Added Range42`
+- `fix: [md] Fixing content regression`
+- `new: [doc] Added LICENCE and README`
+- `new: [pic] Added scandale logo`
+
+Use imperative verbs and keep unrelated changes in separate commits.
+
+## Git Workflow
+
+- **Main branch**: `theme_kode` (this is the default deployment branch)
+- Development branches are merged via pull requests
+- GitHub Actions automatically deploys to Pages on push to `theme_kode`
+- Always run `hugo --cleanDestinationDir --minify` before submitting PR
+
+## Adding a New Project
+
+1. Create `content/projects/project-name.md` with required front matter
+2. Add project logo to `static/img/logo-project-name.png`
+3. Ensure the `repository` field points to the correct GitHub repo (org/repo format)
+4. Set `draft = false` when ready to publish
+5. The `{{< readme >}}` shortcode will automatically fetch and display the project's README from GitHub
+
+## Testing Checklist
+
+- Use `draft = true` while developing new content
+- Run `hugo server -D` to preview drafts locally
+- Run `hugo --panicOnWarning` to catch errors (broken front matter, missing assets, shortcode errors)
+- Verify project README renders correctly via the `{{< readme >}}` shortcode
+- Check for browser console warnings after Sass changes
+- Ensure all project logos exist in `static/img/`
diff --git a/config.toml b/config.toml
@@ -9,11 +9,17 @@ main_button_sub = "powered by the two centres hosted at the Luxembourg House of
 subtitle = "**Open source software is more important than ever!** *And we are committed to improve and cyber secure the society through open technologies.*"
 copyright = "The Luxembourg House of Cybersecurity - Attribution-ShareAlike 4.0 International (CC BY-SA 4.0)"
 
-enableRobotsTXT = true
-Paginate = 4
+[pagination]
+    pagerSize = 4
 
+enableRobotsTXT = true
 theme = "kode"
 
+[markup]
+    [markup.goldmark]
+        [markup.goldmark.renderer]
+            unsafe = true
+
 [taxonomies]
     tag = "tags"
 
@@ -54,4 +60,3 @@ theme = "kode"
         title = "CyberSecurityLuxembourg GitHub account"
         icon = "fa-github"
         url = "https://github.com/CybersecurityLuxembourg"
-
diff --git a/content/projects/coral.md b/content/projects/coral.md
@@ -7,7 +7,6 @@ image_alt: "Logo of CORAL"
 logo: "logo-coral.png"
 weight: 60
 tags: ["projects", "coral", "nc3"]
-logo: "logo_nc3.jpg"
 author: "NC3"
 draft: true
 ---
diff --git a/layouts/shortcodes/readme.html b/layouts/shortcodes/readme.html
@@ -1,2 +1,12 @@
-{{ $data := resources.GetRemote ( printf "https://raw.githubusercontent.com/%s/master/README.md"  $.Page.Params.repository) }}
-{{ $data.Content | markdownify | safeHTML }}
+{{ $repo := $.Page.Params.repository }}
+{{ if not $repo }}
+  {{ errorf "readme shortcode requires a `repository` parameter on %q" $.Page.File.Path }}
+{{ else }}
+  {{ $url := printf "https://raw.githubusercontent.com/%s/master/README.md" $repo }}
+  {{ with resources.GetRemote $url }}
+    {{ .Content | markdownify | safeHTML }}
+  {{ else }}
+    {{ warnf "readme shortcode: unable to fetch %q" $url }}
+  <p><a href="{{ printf "https://github.com/%s" $repo }}">View the project README on GitHub</a></p>
+  {{ end }}
+{{ end }}
