Skip to content

Commit cade897

Browse files
SteveClementSteveClement
authored
Merge pull request #20 from NC3-LU/codex
new: [cicd] Add OCD generation workflow and CLAUDE.md
2 parents 1c43ee8 + 6dd80df commit cade897

3 files changed

Lines changed: 182 additions & 0 deletions

File tree

‎.github/workflows/ocd.yml‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
name: Generate Open Contributions Descriptor
2+
3+
on:
4+
schedule:
5+
# Every Monday at 04:00 UTC
6+
- cron: '0 4 * * 1'
7+
workflow_dispatch:
8+
push:
9+
branches: ["theme_kode"]
10+
paths:
11+
- 'content/projects/**'
12+
- 'data/authors/**'
13+
14+
permissions:
15+
contents: write
16+
17+
defaults:
18+
run:
19+
shell: bash
20+
21+
jobs:
22+
generate-ocd:
23+
runs-on: ubuntu-latest
24+
steps:
25+
- name: Checkout
26+
uses: actions/checkout@v4
27+
with:
28+
ref: theme_kode
29+
30+
- name: Set up Python
31+
uses: actions/setup-python@v5
32+
with:
33+
python-version: '3.11'
34+
35+
- name: Install dependencies
36+
run: pip install requests
37+
38+
- name: Download OCD generator
39+
run: |
40+
curl -fsSL \
41+
https://raw.githubusercontent.com/ossbase-org/Open-Contributions-Descriptor/refs/heads/main/bin/github-to-ocd.py \
42+
-o github-to-ocd.py
43+
44+
- name: Generate OCD — CIRCL
45+
env:
46+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
47+
run: |
48+
python github-to-ocd.py \
49+
--org CIRCL \
50+
--domain code.lhc.lu \
51+
--output ocd.json
52+
53+
- name: Merge OCD — NC3-LU
54+
env:
55+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
56+
run: |
57+
python github-to-ocd.py \
58+
--org NC3-LU \
59+
--domain code.lhc.lu \
60+
--input ocd.json \
61+
--merge-projects \
62+
--output ocd.json
63+
64+
- name: Merge OCD — CybersecurityLuxembourg
65+
env:
66+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
67+
run: |
68+
python github-to-ocd.py \
69+
--org CybersecurityLuxembourg \
70+
--domain code.lhc.lu \
71+
--input ocd.json \
72+
--merge-projects \
73+
--output ocd.json
74+
75+
- name: Install to static well-known
76+
run: |
77+
mkdir -p static/.well-known
78+
cp ocd.json static/.well-known/open-contributions.json
79+
80+
- name: Commit and push if changed
81+
run: |
82+
git config user.name "github-actions[bot]"
83+
git config user.email "github-actions[bot]@users.noreply.github.com"
84+
git add static/.well-known/open-contributions.json
85+
git diff --cached --quiet && echo "No changes to OCD file." || \
86+
git commit -m "upd: [ocd] Regenerate open-contributions.json" && \
87+
git push

‎AGENTS.md‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Repository Guidelines
2+
3+
Use this guide when contributing to Code @ LHC's Hugo site to keep content consistent and builds reliable.
4+
5+
## Project Structure & Module Organization
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.
13+
14+
## Build, Test, and Development Commands
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.
20+
21+
## Coding Style & Naming Conventions
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.
27+
28+
## Testing Guidelines
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.
35+
36+
## Commit & Pull Request Guidelines
37+
- Follow the existing `type: [scope] message` pattern (e.g. `new: [project] Add Range42`) using imperative verbs.
38+
- Group related changes per commit, separating content edits from theme updates to ease review.
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.
41+
42+
## Security & Configuration Tips
43+
- Global settings live in `config/_default/`; review `params.toml` before introducing site-wide toggles.
44+
- 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.

‎CLAUDE.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Project Overview
6+
7+
**Code @ LHC** is a Hugo-based static site serving as the official open source software catalog for the Luxembourg House of Cybersecurity (LHC), showcasing cybersecurity projects from CIRCL and NC3-LU. Deployed to GitHub Pages from the `theme_kode` branch.
8+
9+
## Commands
10+
11+
```bash
12+
# Local development (port 1313, includes drafts, auto-reload)
13+
hugo server -D --disableFastRender
14+
15+
# Production build (output to public/)
16+
hugo --minify --gc
17+
18+
# After cloning or switching branches
19+
git submodule update --init --recursive
20+
```
21+
22+
There are no automated tests — verify changes locally via `hugo server`, checking the console for warnings about missing resources or broken links.
23+
24+
## Architecture
25+
26+
**Stack:** Hugo v0.108.0, `kode` theme (git submodule), Dart Sass Embedded for SCSS compilation via Hugo Pipes.
27+
28+
**Content model:**
29+
- `content/projects/*.md` — One file per project with TOML front matter: `title`, `author` (references `data/authors/*.toml`), `description`, `logo`, `weight` (sort order), `repository` (GitHub org/repo path). Body typically uses `{{< readme >}}` shortcode.
30+
- `layouts/shortcodes/readme.html` — Fetches each project's `README.md` from GitHub at **build time** using Hugo's `resources.GetRemote`. Requires the project's default branch to be `master`.
31+
- `data/homepage.yml` — Drives homepage sections (banner, highlights, CTA).
32+
- `data/authors/` — Author metadata (CIRCL.toml, NC3.toml) referenced by project front matter.
33+
- `config/_default/menus.toml` — Navigation config.
34+
- `assets/sass/custom.scss` — Site-specific SCSS compiled by Hugo Pipes.
35+
- `static/img/` — Project logos referenced by filename in project front matter.
36+
37+
**Theme customization:** Override theme templates in the root `layouts/` directory. Do not edit `themes/kode/` directly — it is a git submodule.
38+
39+
**Deployment:** GitHub Actions (`.github/workflows/hugo.yml`) triggers on push to `theme_kode` branch, builds with `HUGO_ENVIRONMENT=production`, and deploys `public/` to GitHub Pages.
40+
41+
## Conventions
42+
43+
**Commit messages:** `type: [scope] message`
44+
- Examples: `new: [project] Add Range42`, `fix: [cicd] Fixed out of date actions`, `new: [pic] Added scandale logo`
45+
- Common types: `new`, `fix`, `upd`, `del`
46+
47+
**Files:** snake_case filenames, Markdown with TOML front matter, ~100 char line wrap, SCSS with 2-space indent.
48+
49+
**Adding a project:** Create `content/projects/<name>.md` with TOML front matter, add logo to `static/img/`, ensure the GitHub repo's default branch is `master` for the readme shortcode to work.
50+
51+
**Branch targeting:** All work destined for production must merge to `theme_kode` (not `main`/`master`).

0 commit comments

Comments
 (0)