diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 0000000..accb2f5 --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,216 @@ +# OpenCHAMI.org Copilot Instructions + +## Project Overview + +**OpenCHAMI.org** is a Hugo-based static documentation site for the [OpenCHAMI project](https://openchami.org), an open-source HPC system management platform. The site uses the **Doks theme** (via `@hyas/doks-core`) to build and deploy technical documentation, blog posts, events, and community contributor profiles. + +**Key Tech Stack:** +- Hugo (0.123.7) for static site generation +- Node.js + pnpm for dependency management +- SCSS/CSS for styling (with Tabler Icons) +- Netlify for hosting and CI/CD +- REUSE specification for licensing compliance + +## Critical Developer Workflows + +### Local Development +```bash +npm install # Install dependencies (includes Hugo) +npm run dev # Start dev server at http://localhost:1313 +npm run dev:drafts # Include draft pages (--buildDrafts) +npm run build # Production build +npm run preview # Preview production build locally +``` + +### Content Management +```bash +npm run create path/to/content # Create new content with archetype scaffolding +npm run lint # Run all linters (scripts, styles, markdown) +npm run clean # Remove build artifacts and caches +``` + +### Cleaning Build Issues +The site uses Hugo's build cache which can occasionally cause stale content. If pages don't update or the build fails unexpectedly: +```bash +rm -rf public resources .hugo_build.lock +npm run dev # Restart server +``` + +## Content Organization & Conventions + +### Directory Structure +- **`content/`** – All markdown content (main source of truth) + - `blog/` – Blog posts and articles (multiple subdirectories for organization) + - `docs/` – Technical documentation, guides, architecture + - `events/` – Conferences and community events + - `contributors/` – Community member profiles + - `announcements/` – Press releases and major announcements + - `about-us/` – General company/project information + - `news/` – News items + +- **`layouts/`** – Hugo templates (mostly inherited from Doks) + - `index.html` – Custom homepage (modified extensively) + - `_default/`, `docs/`, `partials/`, `shortcodes/` + +- **`config/_default/`** – Hugo configuration + - `hugo.toml` – Core Hugo settings (title, baseURL, outputs) + - `params.toml` – Theme parameters and Doks customization + - `languages.toml` – Multilingual config (single language currently) + - `module.toml` – Asset mounting (mounts node_modules resources) + - `markup.toml` – Markdown parsing settings + +- **`assets/`** – SCSS, JavaScript, images, SVGs (compiled and bundled) + +### Front Matter Conventions + +**Blog Posts & Documentation:** +```toml ++++ +title = "Post Title" +description = "Short summary for SEO" +date = 2024-01-15T10:00:00+00:00 +lastmod = 2024-01-15T10:00:00+00:00 +draft = false +weight = 50 # Sort order (lower = earlier) +contributors = ["GitHub Username"] ++++ +``` + +**Key Fields:** +- `date` – Publication date (ISO 8601 format) +- `draft` – Set to `true` to hide from production (visible with `npm run dev:drafts`) +- `weight` – Controls ordering in lists and navigation (not always present) +- `contributors` – List of GitHub usernames +- `homepage` – If `true`, featured on homepage (used sparingly) + +### Taxonomies +- **Contributors** – Defined in `config/_default/hugo.toml` as taxonomy `contributors` +- **Tags & Categories** – Auto-generated from content organization + +## Key Files & Patterns + +### Homepage Customization +[layouts/index.html](layouts/index.html) – Heavily customized HTML (not inherited from Doks): +- Three-column feature section (Security, Simplicity, Modularity) +- Call-to-action buttons linking to `/docs/tutorial/` +- Newsletter signup form (Mailerlite integration) +- YouTube video embed shortcode +- **Do NOT edit Doks theme files directly** – customize via parameters in `config/` + +### Hugo Configuration Priorities +Hugo loads config in this order (most specific wins): +1. `config/` (base) +2. `config/_default/` (default environment) +3. `config/production/` or `config/next/` (environment-specific) +4. Command-line flags override everything + +### Theme Inheritance +- **Base theme**: `@hyas/doks-core` (npm package in `node_modules/`) +- **Customization points**: + - Override Doks parameters in `config/_default/params.toml` + - Add custom layouts/partials in `layouts/` (they shadow theme files) + - Custom SCSS in `assets/scss/` (mounted to override theme CSS) + - Example: `flexSearch`, `navbarSticky`, `colorMode` parameters control theme behavior + +## Search & Navigation Configuration + +The site uses **FlexSearch** for full-text search: +- Index generated in JSON format (`hugo_stats.json`, `search-index.json`) +- Configured in `params.toml`: `searchLimit = 99`, `indexSummary = false` +- Excludes content types via `searchExclTypes` (customize as needed) +- Navigation menus in `config/_default/menus/` + +## Deployment & Hosting + +**Netlify Configuration** ([netlify.toml](netlify.toml)): +- Build command: `pnpm build` +- Publish directory: `public/` +- Environment contexts for production, deploy-preview, branch-deploy, and "next" branch +- Node version: 18.16.1, NPM: 9.5.1 + +**Manual Deployment Workflow:** +1. Merge to main branch +2. Local testing required before merge (no auto-deploy on PR) +3. Manual release to hosting after approval +4. Deploy via `npm run deploy` (requires S3 credentials) + +## Licensing & REUSE Compliance + +This project follows the **REUSE specification** (https://reuse.software/): +- Primary license: MIT (`LICENSE`, `LICENSES/MIT.txt`) +- Metadata: `REUSE.toml` in repo root +- All files implicitly licensed MIT by `REUSE.toml` aggregate annotation +- CI check: `.github/workflows/reuse.yml` validates compliance +- To verify: `reuse lint` (requires Python + REUSE tool) + +**No need to add license headers** to markdown files – covered by aggregate rule. + +## Linting & Code Quality + +**Lint Commands:** +- `npm run lint` – Run all linters +- `npm run lint:scripts` – ESLint (JavaScript in `assets/js/`) +- `npm run lint:styles` – Stylelint (SCSS in `assets/scss/`) +- `npm run lint:markdown` – Markdownlint (all `.md` files) + +**Cache Management:** Linters cache results in `.eslintcache`, `.stylelintcache`. Use `npm run clean:lint` to reset. + +## Branch & Contribution Workflow + +- **Branch naming**: `/` (enforced by convention) +- **Merge strategy**: Branches deleted after merge; no automatic deploy +- **Testing**: Build locally (`npm run build`) and preview before PR +- **PR validation**: `.github/workflows/validate_pr.yml` runs build check on every PR + +## Common Tasks & Patterns + +### Adding a Blog Post +1. Create directory: `content/blog//` +2. Create `_index.md` with front matter (use archetype: `npm run create blog/`) +3. Add additional pages as needed (e.g., `introduction.md` for sub-sections) +4. Reference images relative to the directory + +### Adding Documentation +- Place in `content/docs/
/` +- Use weight to control order +- Link to other docs with relative paths (Hugo rewrites them) +- Include in navigation via `config/_default/menus/` + +### Adding Events +- Create in `content/events///` +- Example: `content/events/Conferences/2026/HPSFCon26.md` +- Can use `layout = "cards"` for special card-based display + +### Custom Shortcodes +Available Doks shortcodes: +- `{{< youtube VIDEO_ID >}}` – Embed YouTube videos +- Check `layouts/shortcodes/` for others + +## GitHub Actions Workflows + +- **`validate_pr.yml`** – Runs `npm install` + `npm run build` on PRs (blocks merge if build fails) +- **`reuse.yml`** – Validates REUSE compliance +- **`S3_Deploy_Hugo.yml`** – Handles production S3 deployment + +## Debugging Tips + +**Hugo not found?** Clear install cache: +```bash +npm run clean:install && npm install +``` + +**Stale content in dev server?** +```bash +rm -rf public resources .hugo_build.lock && npm run dev +``` + +**Build passes locally but fails in CI?** Check: +- Node version (18.16.1 on Netlify, verify locally) +- pnpm version (>= 8.10.0) +- Hugo version in `package.json` → `otherDependencies.hugo` +- All dependencies installed: `npm install` + +**CSS/JS not updating?** Clear asset cache: +```bash +npm run clean && npm install && npm run dev +``` diff --git a/config/_default/hugo.toml b/config/_default/hugo.toml index 70516a5..4f8c0f5 100644 --- a/config/_default/hugo.toml +++ b/config/_default/hugo.toml @@ -1,7 +1,7 @@ title = "OpenCHAMI" baseurl = "/" canonifyURLs = false -disableAliases = true +disableAliases = false disableHugoGeneratorInject = true # disableKinds = ["taxonomy", "term"] enableEmoji = true @@ -14,7 +14,7 @@ rssLimit = 10 summarylength = 20 # 70 (default) -copyRight = "Copyright (c) 2023-2024 OpenCHAMI" +copyRight = "Copyright (c) 2023-2026 OpenCHAMI" diff --git a/content/events/Conferences/2026/UCL-DevSummit.md b/content/events/Conferences/2026/UCL-DevSummit.md deleted file mode 100644 index e5485f7..0000000 --- a/content/events/Conferences/2026/UCL-DevSummit.md +++ /dev/null @@ -1,23 +0,0 @@ -+++ -title = 'OpenCHAMI Developer Summit @ UCL' -date = 2025-11-17 -start_date = 2026-05-01 -end_date = 2026-05-25 -draft = false -categories = ['Summit', 'Development', 'Community'] -contributors = [] -+++ - -**Event**: OpenCHAMI Developer Summit at University College London - -**Date**: TBD (2026) - -**Location**: London, United Kingdom - -**Website**: TBD - -Join us for a developer-focused summit to collaborate on OpenCHAMI's future. **Dates are to be determined.** - -**Want to help plan this event?** Find us on [Slack](/slack) to get involved! - -Read more about OpenCHAMI [here](/docs/introduction-to-openchami/) and try it yourself through the [install guide](/guides/getting_started/). diff --git a/content/events/Summits/2026/UCL26.md b/content/events/Summits/2026/UCL26.md new file mode 100644 index 0000000..199abee --- /dev/null +++ b/content/events/Summits/2026/UCL26.md @@ -0,0 +1,112 @@ ++++ +title = 'OpenCHAMI Developer Summit @ UCL 2026' +date = 2026-01-09 # page publication date +start_date = 2026-05-07 +end_date = 2026-05-08 +draft = false +categories = ['Summit', 'Development', 'HPC'] +contributors = ["Alex Lovell-Troy",] +aliases = ["/events/summits/ucl-2026/", "/ucl26/"] ++++ + + +### University College London • London, UK • May 7th – 8th 2026 +**Event**: OpenCHAMI Developer Summit @ UCL 2026 + + +**Date**: May 7-8, 2026 + +**Location**: University College London, London, UK + +**Website**: [UCL26](https://openchami.org/ucl26/) + +**Hosts**: BriCS, UCL, Cambridge, OpenCHAMI Community + +**Slack**: [#2026-uk-dev-summit](https://openchami.slack.com/archives/C09V62C7DGX) + +## Who Should Attend? + +- **Sysadmins** deploying or evaluating OpenCHAMI in production +- **Developers** who want to contribute code, docs, or integrations +- **HPC practitioners & researchers** curious about automated system management +- Anyone interested in **community-driven, vendor-neutral** HPC tooling + +--- + +## Why Attend? + +- **Network** with OpenCHAMI contributors, site admins, and developers +- **Learn** best practices for large-scale HPC automation and orchestration +- **Shape** the project’s future via live RFD and governance sessions +- **Hack** on real code and docs to advance the OpenCHAMI roadmap + +--- + +## Event Details + +The OpenCHAMI community is gathering at UCL for three days of collaboration, learning and hacking. Whether you’re new to OpenCHAMI or a long‑time contributor, there will be tracks for every skill level. Meet fellow sysadmins, developers and researchers working on open HPC automation and help shape the project’s future. + +--- + +## Location & Directions + + +**Venue:** . + + +--- + + +## Agenda Snapshot + +| Day | Theme | Highlights | +|---|---|---| +| **Day 1 – ** | *TBD* | TBD | +| **Day 2 – ** | *TBD* | TBD | + +## Schedule +*(All times Local)* + +### Day 1 – Thursday, May 7th + +| Time | Session & Speakers | Room | +| --- | --- | --- | + + + +--- + +### Day 2 – Friday, May 8th + + +| Time | Session & Speakers | Room | +| --- | --- | --- | + + +--- + +## Tracks & Chairs +- **Architecture:** Alex Lovell-Troy — [alovelltroy@lanl.gov](mailto:alovelltroy@lanl.gov) + +--- + +## Registration +Registration is required for attendance. Please secure your spot by visiting our [Registration page](https://pretix.eu/ARC/ochami-ucl-2026/). Capacity is limited and on-site meals are provided based on registration. + + + +--- + +## Sponsors +We’re grateful to our sponsors for supporting the OpenCHAMI Developer Summit. Sponsor information and logos will appear here soon. If your organization is interested in sponsoring the event, please contact us at [contact@openchami.org](mailto:contact@openchami.org). + +--- + +> **We look forward to seeing you at UCL!** +> A formal invitation with hotel and travel details will follow shortly. +> For questions or attendee suggestions, email **[contact@openchami.org](mailto:contact@openchami.org)**. + +--- +*Save the date and stay tuned for more updates!*