Skip to content

Commit 5007478

Browse files
SteveClementSteveClement
committed
new: [llm] Added codex/claude .md
1 parent cb58380 commit 5007478

File tree

2 files changed

+148
-17
lines changed

2 files changed

+148
-17
lines changed

‎AGENTS.md‎

Lines changed: 28 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -1,32 +1,43 @@
11
# Repository Guidelines
22

3+
Use this guide when contributing to Code @ LHC's Hugo site to keep content consistent and builds reliable.
4+
35
## Project Structure & Module Organization
4-
- `content/` houses Markdown with TOML front matter; subfolders mirror site navigation and service areas.
5-
- `layouts/` overrides theme templates; keep page partials grouped by section to avoid collisions.
6-
- `assets/` collects SCSS and pipeline assets compiled by Hugo Extended.
7-
- `static/` serves images and downloads verbatim; store heavy media externally and link here.
8-
- `data/` exposes YAML/TOML snippets consumed by shortcodes, ideal for project inventories.
9-
- `themes/` includes `kode` (active) and `hugo-arcana`; treat them as git submodules and avoid direct edits without upstream PRs.
6+
- `content/` houses Markdown with TOML front matter; subfolders mirror site navigation and service areas. Prefer Hugo shortcodes (e.g. `readme`) over raw HTML embeds.
7+
- `layouts/` and `layouts/shortcodes/` override theme templates; keep page partials grouped by section to avoid collisions.
8+
- `assets/sass/` contains the SCSS processed by Hugo Extended; rely on the Hugo Pipes pipeline instead of committing compiled CSS.
9+
- `static/` serves images and downloads verbatim; store heavy media externally and link here only when needed.
10+
- `data/` exposes YAML/TOML snippets consumed by shortcodes, ideal for project inventories and shared content blocks.
11+
- `themes/kode` (active) and `themes/hugo-arcana` are git submodules; sync them before editing and avoid direct changes without upstream pull requests.
12+
- `public/` is generated build output; never edit it manually.
1013

1114
## Build, Test, and Development Commands
12-
- `hugo server -D --disableFastRender` starts a local preview with drafts and reloads assets on each request.
13-
- `hugo --minify --gc` produces the production bundle in `public/`, pruning unused fingerprinted assets.
14-
- `git submodule update --init --recursive` syncs theme sources after cloning or switching branches.
15+
- `git submodule update --init --recursive` ensures theme sources are available after cloning or switching branches.
16+
- `hugo server -D --disableFastRender` runs a local preview with drafts enabled and reloads assets on each request (http://localhost:1313).
17+
- `hugo --cleanDestinationDir --gc --minify` mirrors the CI build, prunes unused assets, and writes fresh output to `public/`; run before pushing.
18+
- `hugo --panicOnWarning` catches missing resources, shortcode errors, or front matter issues during review.
19+
- `npm ci` (optional) installs theme tooling when a `package-lock.json` is introduced or updated.
1520

1621
## Coding Style & Naming Conventions
17-
- Author content in Markdown with TOML front matter; use snake_case filenames for multi-word slugs.
18-
- Wrap prose near 100 characters and prefer semantic Markdown (lists, tables) over ad-hoc HTML.
19-
- Keep SCSS indented with two spaces and rely on Hugo Pipes; do not commit compiled CSS.
22+
- 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.
23+
- Author content in Markdown with TOML front matter; wrap prose near 100 characters and prefer semantic Markdown (lists, tables) over ad-hoc HTML.
24+
- 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.
25+
- Keep SCSS indented with two spaces and organized by component; do not commit generated CSS.
26+
- Place reusable snippets in `layouts/shortcodes/` instead of embedding raw HTML directly in content files.
2027

2128
## Testing Guidelines
22-
- Verify new pages via `hugo server` and watch for console warnings about missing resources or broken links.
23-
- Before pushing, run `hugo --minify` locally and open `public/index.html` to spot layout regressions.
24-
- The repository has no automated unit tests; document manual verification steps in the pull request description.
29+
- Toggle `draft = true` while iterating on new pages, flipping to `false` only when ready to publish.
30+
- Verify new or updated pages via `hugo server` and watch the terminal/browser console for warnings about missing resources or broken links.
31+
- Run `hugo --cleanDestinationDir --gc --minify` locally and spot-check `public/index.html` (or affected pages) for layout regressions.
32+
- Use `hugo --panicOnWarning` to fail fast on front matter or shortcode issues.
33+
- After Sass changes, confirm compiled styles in the browser and resolve any console warnings.
34+
- The repository has no automated unit tests; document manual verification steps in pull requests.
2535

2636
## Commit & Pull Request Guidelines
27-
- Follow the existing `type: [scope] message` pattern (e.g., `new: [project] Add Range42`) and keep messages imperative.
37+
- Follow the existing `type: [scope] message` pattern (e.g. `new: [project] Add Range42`) using imperative verbs.
2838
- Group related changes per commit, separating content edits from theme updates to ease review.
29-
- Pull requests should link related issues, describe the change, list manual checks, and attach screenshots for UI adjustments.
39+
- Pull requests should link related issues, describe the change, list manual checks (commands run), and attach screenshots or GIFs for UI adjustments.
40+
- Confirm `hugo --cleanDestinationDir --minify` (and other relevant checks) passes before requesting review.
3041

3142
## Security & Configuration Tips
3243
- Global settings live in `config/_default/`; review `params.toml` before introducing site-wide toggles.

‎CLAUDE.md‎

Lines changed: 120 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,120 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Overview
6+
7+
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.
8+
9+
## Essential Commands
10+
11+
### Setup
12+
```bash
13+
# Clone with theme submodules
14+
git submodule update --init --recursive
15+
16+
# Install optional Node.js dependencies (if needed by theme)
17+
npm ci
18+
```
19+
20+
### Development
21+
```bash
22+
# Run local dev server with drafts enabled
23+
hugo server -D --disableFastRender
24+
25+
# Access at http://localhost:1313
26+
```
27+
28+
### Build & Testing
29+
```bash
30+
# Production build (matches CI pipeline)
31+
hugo --cleanDestinationDir --gc --minify
32+
33+
# Build with strict error checking
34+
hugo --panicOnWarning
35+
```
36+
37+
## Architecture
38+
39+
### Content Management
40+
- **Project pages**: Each project is a Markdown file in `content/projects/` with TOML front matter
41+
- **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
42+
- **Homepage configuration**: `data/homepage.yml` controls the homepage layout and content sections
43+
44+
### Required Front Matter for Projects
45+
```toml
46+
+++
47+
title = "Project Name"
48+
author = "CIRCL" # or "NC3"
49+
description = "Brief description"
50+
logo = "logo-project.png" # Must exist in static/img/
51+
weight = 10 # Controls display order
52+
draft = false
53+
repository = "org/repo" # GitHub repo path for {{< readme >}} shortcode
54+
tags = ["projects", "tag1", "tag2"]
55+
+++
56+
```
57+
58+
### Theme System
59+
- Primary theme: `kode` (located in `themes/kode/`)
60+
- Themes are **git submodules** - always sync before editing theme assets
61+
- Override theme templates by placing files in root `layouts/` directory
62+
- Custom shortcodes: `layouts/shortcodes/` (readme.html, osm.html, rawhtml.html)
63+
64+
### Static Assets
65+
- `static/img/` - Project logos and images (served as-is)
66+
- `static/images/` - Banner and site images
67+
- `assets/sass/` - Source styles (processed by Hugo's asset pipeline)
68+
- `public/` - Generated build output (never edit manually, excluded from git)
69+
70+
### Configuration
71+
- `config.toml` - Main Hugo configuration
72+
- Base URL: https://code.lhc.lu
73+
- Theme: kode
74+
- Hugo version used in CI: 0.108.0 (specified in `.github/workflows/hugo.yml`)
75+
- Social links and menu configuration
76+
77+
## Code Style (from .editorconfig)
78+
79+
- **Default**: 4-space indentation
80+
- **HTML/CSS/JS/YAML**: 2-space indentation
81+
- **Makefiles**: Tab indentation
82+
- **Encoding**: UTF-8 with LF line endings
83+
- **Markdown**: May retain intentional double trailing spaces (for line breaks)
84+
- Always include trailing newline
85+
86+
## Commit Message Format
87+
88+
Follow existing pattern: `type: [scope] message`
89+
90+
Examples:
91+
- `new: [project] Added Range42`
92+
- `fix: [md] Fixing content regression`
93+
- `new: [doc] Added LICENCE and README`
94+
- `new: [pic] Added scandale logo`
95+
96+
Use imperative verbs and keep unrelated changes in separate commits.
97+
98+
## Git Workflow
99+
100+
- **Main branch**: `theme_kode` (this is the default deployment branch)
101+
- Development branches are merged via pull requests
102+
- GitHub Actions automatically deploys to Pages on push to `theme_kode`
103+
- Always run `hugo --cleanDestinationDir --minify` before submitting PR
104+
105+
## Adding a New Project
106+
107+
1. Create `content/projects/project-name.md` with required front matter
108+
2. Add project logo to `static/img/logo-project-name.png`
109+
3. Ensure the `repository` field points to the correct GitHub repo (org/repo format)
110+
4. Set `draft = false` when ready to publish
111+
5. The `{{< readme >}}` shortcode will automatically fetch and display the project's README from GitHub
112+
113+
## Testing Checklist
114+
115+
- Use `draft = true` while developing new content
116+
- Run `hugo server -D` to preview drafts locally
117+
- Run `hugo --panicOnWarning` to catch errors (broken front matter, missing assets, shortcode errors)
118+
- Verify project README renders correctly via the `{{< readme >}}` shortcode
119+
- Check for browser console warnings after Sass changes
120+
- Ensure all project logos exist in `static/img/`

0 commit comments

Comments
 (0)