Skip to content

CLAUDE.md

Latest commit

 

History

History
279 lines (235 loc) · 12.6 KB

CLAUDE.md

File metadata and controls

279 lines (235 loc) · 12.6 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Hugo static site for Hartza Capital, a growing fintech SME developing alternative investment management capabilities. The site uses the hugo-serif-theme as a base with extensive customizations for corporate branding and multilingual support.

Development Commands

# Start development server
npm run dev
# or: hugo server -D

# Build for production (with fresh headers)
npm run build
# or: hugo --minify

# Build with specific environment
npm run build:production
# or: hugo --environment production

# Generate dynamic headers only
npm run headers

# Clean build cache
npm run clean
# or: hugo mod clean

# Serve for network access
npm run serve

Dynamic Headers System

The site uses automatic HTTP header generation for optimal CDN caching:

  • Script: /scripts/generate-headers.js - Calculates expiration dates automatically
  • Pre-build: /scripts/pre-build.js - Runs automatically before Hugo build
  • Output: /static/_headers - CDN-ready headers with current timestamps
  • Automation: Fully automated in all environments (dev, build, production)
  • Manual: Use npm run headers to regenerate headers only

Deployment Integration:

  • GitHub Actions: .github/workflows/build.yml - Auto-generates headers in CI/CD
  • Cloudflare Pages: cloudflare-pages.yml - Production build with fresh headers
  • Netlify: netlify.toml - Alternative deployment with header automation
  • Local: npm run dev or npm run build - Always generates fresh headers

Zero Configuration: Headers are automatically regenerated on every build with correct expiration dates!

Architecture & Key Components

Theme Structure

  • Base Theme: hugo-serif-theme in /themes/
  • Custom Overrides: All customizations in /layouts/ override theme defaults
  • Asset Pipeline: SCSS compilation and JS bundling through Hugo Pipes

Multilingual Setup

  • Languages: French (default), English
  • Content Structure: /content/fr/ and /content/en/
  • Configuration: Language-specific menus and parameters in hugo.toml
  • URL Structure: /fr/ and /en/ prefixes

Logo System

The site uses a sophisticated logo switching system:

  • Navbar: Short logos (logo-short.png / black-short.png) with theme-based switching
  • Hero Section: Full logo (logo.png) on homepage
  • Logic: Light theme = dark logo, dark theme = light logo (for contrast)

Theme System (Dark/Light Mode)

Comprehensive theming with:

  • CSS Variables: All colors defined in :root and [data-theme="dark"]
  • Auto-detection: Respects system preference via prefers-color-scheme
  • Persistence: Theme choice stored in localStorage
  • Toggle: Navbar integration with smooth transitions

Styling Architecture

  • Primary Styles: ares-style.scss - Corporate design inspired by Ares Management
  • Theme System: theme-system.scss - Dark/light mode CSS variables
  • Typography: Poppins (headings) + Inter (body text) from Google Fonts
  • Responsive: Mobile-first Bootstrap grid system

Key Configuration (hugo.toml)

# Logo configuration with theme switching
[params.logo]
  desktop_light = "/images/logo/black-short.png"  # Dark logo for light theme
  desktop_dark = "/images/logo/logo-short.png"    # Light logo for dark theme
  hero_logo = "/images/logo/logo.png"             # Full logo for homepage

# Pagination configuration (Hugo v0.128.0+)
[pagination]
  pagerSize = 10
  path = "page"

# Multilingual menus
[[languages.fr.menu.main]]
[[languages.en.menu.main]]

Custom JavaScript Components

  • Theme Manager: /assets/js/theme-manager.js - Handles theme switching and persistence
  • Newsletter System: /assets/js/newsletter.js - Smart newsletter modal triggering with TTL persistence
  • Integration: All loaded via Hugo Pipes in page templates

Newsletter JavaScript Features

  • TTL Storage Functions: setItemWithTTL() and getItemWithTTL() for time-limited localStorage
  • Automatic Expiration: Newsletter scroll modals reappear after 3 days
  • Backwards Compatibility: Handles legacy localStorage entries without TTL
  • Context Separation: Different storage keys for blog modals vs. homepage interactions

Content Strategy

  • Homepage: Corporate positioning as "growing alternative investment manager"
  • Messaging: Focus on PME status with expansion ambitions across credit, real estate, private equity, infrastructure
  • Tone: Professional yet transparent about current scale and future vision

Layout Overrides

Key files that override theme defaults:

  • /layouts/index.html - Custom homepage with video carousel and corporate messaging
  • /layouts/partials/header.html - Enhanced navbar with theme toggle and language switcher
  • /layouts/partials/language-switcher.html - Intelligent language switching with three-tier fallback system
  • /layouts/partials/theme-toggle.html - Dark/light mode toggle for navbar

Asset Processing

All custom assets processed through Hugo Pipes:

  • SCSS compilation with source maps in development
  • JavaScript bundling and minification in production
  • Automatic cache busting via fingerprinting
  • Component-specific CSS loading (glossary, newsletter, etc.)
  • Intelligent JavaScript module loading and dependency management

Important Notes

Content Tagging System

Articles support conditional disclaimers through strategic tagging:

---
title: "Investment Analysis Article"
tags: ["finance", "own", "analysis"]
categories: ["Investment"]
---
  • "finance" tag: Triggers comprehensive financial disclaimer with investment warnings
  • "own" tag: Triggers ownership disclosure about Hartza Capital's potential stake
  • Multiple tags: Both disclaimers can appear simultaneously if both tags present
  • Position: Disclaimers appear at article start for maximum transparency

Logo File Requirements

  • Standard logos: PNG format, transparent background
  • Naming convention: logo.png (light), black.png (dark), *-short.png (navbar versions)
  • Height: 42px for navbar, 80px for hero section

Theme Color Palette

  • Primary Navy: #1a2332
  • Primary Blue: #2563eb
  • Corporate theme follows Ares Management aesthetic with professional color scheme

Page Layout System

Each section requires proper layout override for navbar/footer integration:

  • Critical: All page layouts must include {{ define "body_classes" }}page-[section] ares-style{{ end }}
  • Required CSS: ares-style.scss, theme-system.scss, footer-ares.scss, page-content.scss
  • Script Integration: theme-manager.js for theme switching functionality

Layout File Structure

/layouts/
├── index.html                 # Homepage with hero section and newsletter
├── _default/
│   └── baseof.html           # Custom base template with proper title format
├── partials/
│   ├── header.html           # Navbar with theme/lang controls
│   ├── footer.html           # Corporate footer
│   ├── theme-toggle.html     # Theme switching component
│   ├── language-switcher.html # Intelligent language selection
│   ├── newsletter-banner.html # Newsletter banner and modal
│   └── newsletter-section.html # Homepage newsletter section
├── blog/
│   ├── list.html            # Blog listing with search and pagination
│   └── single.html          # Individual blog posts (full-width)
├── services/
│   ├── list.html            # Services overview
│   └── single.html          # Service details
└── _default/
    └── single.html          # Default page layout

Blog System

  • Search Functionality: JavaScript-powered real-time search with tag filtering
  • Pagination: 10 articles per page with responsive navigation
  • Styling: Comprehensive blog.scss with grid layout
  • Features: Categories, tags, reading time, responsive design
  • Article Layout: Full-width content with tags positioned under title
  • Content Order: Latest articles first (newest to oldest)
  • Legal Disclaimers: Conditional disclaimers based on article tags
  • Integration: Full navbar and footer styling

Legal Disclaimer System

Advanced conditional disclaimer system for transparency and compliance:

  • Financial Disclaimer: Triggered by "finance" tag, yellow styling with warning icon
  • Ownership Disclaimer: Triggered by "own" tag, blue styling with document icon
  • Position: Displayed at article beginning after header, before content
  • Bilingual Support: Full French/English translations
  • Content Coverage: Investment risks, past performance warnings, professional advice recommendations
  • Transparency: Clear disclosure of Hartza Capital's potential conflicts of interest
  • Styling: Distinct visual styling for each disclaimer type with responsive design

Newsletter System

Advanced newsletter subscription with context-aware behavior:

  • Homepage: Inline form in dedicated section with enhanced styling
  • Blog Pages: Smart modal triggering system
  • Scroll Detection: Modal appears after 60% page scroll on blog articles
  • TTL Persistence: Time-limited localStorage with 3-day expiration for scroll modals
  • Separate Context Management: Independent localStorage keys for different contexts
  • User Experience: Non-intrusive, reappears after TTL expiration
  • Styling: Smooth animations with corporate theme integration

Interactive Glossary System

Advanced tooltip-powered financial glossary for enhanced content comprehension:

  • Shortcode Integration: Simple {{< glossaire "term_key" >}} usage in markdown content
  • Multilingual Data Structure: Unified YAML structure with English keys for easy management
  • Interactive Tooltips: Hover, focus, and click interactions with smooth animations
  • Smart Positioning: Automatic tooltip positioning with mobile-optimized fallbacks
  • Accessibility: Full ARIA support, keyboard navigation, and screen reader compatibility
  • Performance: Intelligent show/hide delays and memory management
  • Responsive Design: Mobile-first approach with touch-friendly interactions
  • Theme Integration: Seamless dark/light theme support with corporate styling

Language Switching System

Advanced three-tier language switching with intelligent fallback:

Priority 1: Direct Translation Detection

  • Uses Hugo's built-in $.IsTranslated and $.Translations system
  • Automatically detects officially linked translations
  • Provides immediate redirection when translations exist

Priority 2: Filename-Based Matching

  • Searches all site pages using $.Site.AllPages for cross-language discovery
  • Compares $.File.BaseFileName across languages
  • Finds corresponding articles even without formal translation links
  • Example: /blog/article.md ↔ /en/blog/article.md

Priority 3: Intelligent Fallback

  • Blog Section: Redirects to blog listing in target language (/en/blog/ or /blog/)
  • Other Sections: Redirects to homepage in target language
  • Prevents dead-end user experiences

Technical Implementation

{{ range $.Site.AllPages }}
  {{ if and (eq .Section "blog") (eq .Language.Lang $targetLang) .File }}
    {{ if eq .File.BaseFileName $currentFile }}
      <!-- Match found, redirect to article -->
    {{ end }}
  {{ end }}
{{ end }}

Page Layout System

  • Width Consistency: All pages now use col-12 for uniform width across homepage, blog, about, services, and contact pages
  • Theme Integration: Consistent ares-style class application
  • Responsive Design: Mobile-first approach with proper Bootstrap grid usage

Development Workflow

  1. All customizations go in /layouts/ and /assets/ (never modify /themes/ directly)
  2. Test both French and English versions
  3. Verify dark/light theme switching
  4. Test responsive behavior on mobile devices
  5. Verify navbar integration on all pages with ares-style class
  6. Test newsletter modal triggering on blog pages
  7. Verify pagination functionality with 10+ articles
  8. Test search and tag filtering on blog listing
  9. Test disclaimer functionality with "finance" and "own" tags
  10. Verify legal disclaimer display in both languages
  11. Test language switching behavior on blog articles with same filenames
  12. Verify TTL-based newsletter modal persistence (3-day expiration)
  13. Test glossary tooltip functionality on hover and keyboard navigation
  14. Verify glossary terms display correctly in both languages
  15. Test glossary tooltip positioning on mobile devices
  16. Ensure glossary accessibility features work with screen readers