214 lines
9.2 KiB
Markdown
214 lines
9.2 KiB
Markdown
# Adritian Hugo Theme - AI Coding Instructions
|
|
|
|
## Project Overview
|
|
|
|
This is a **Hugo theme** for personal websites/portfolios, not a standalone site (although a example site is provided, to demonstrate the usage of the theme itself). The theme provides layouts, styling, and functionality that users import via Hugo modules or as a git submodule.
|
|
|
|
**Technology Stack:**
|
|
- **Static Site Generator:** Hugo (v0.136+ extended version required)
|
|
- **CSS Framework:** Bootstrap 5 (v5.3.8)
|
|
- **CSS Preprocessor:** SCSS/Sass
|
|
- **JavaScript Libraries:** Fuse.js (search), DOMPurify (XSS protection)
|
|
- **Testing:** Playwright (E2E tests)
|
|
- **Package Manager:** npm
|
|
- **Templating:** Hugo Templates (Go templates)
|
|
- **Build Tools:** Hugo's built-in asset pipeline, PostCSS, Autoprefixer
|
|
|
|
## Project Architecture
|
|
|
|
This is a **Hugo theme** for personal websites/portfolios, not a standalone site. The theme provides layouts, styling, and functionality that users import via Hugo modules or as a git submodule.
|
|
|
|
The theme provides a example site (`exampleSite/`) that demonstrates all features and serves as a starting point for users. It is also used for the integration tests.
|
|
|
|
**Key Structure:**
|
|
- `layouts/` - Hugo templates (partials, shortcodes, content types)
|
|
- `assets/scss/` - Bootstrap 5-based styling with theme customizations
|
|
- `exampleSite/` - Demo content that gets distributed to users via `adritian-theme-helper` and serves as a github template repository
|
|
- `archetypes/` - Content templates for different content types
|
|
- `i18n/` - Multilingual translations (en/es/fr)
|
|
|
|
## Content Architecture & Custom Types
|
|
|
|
The theme implements **5 custom content types** with specific frontmatter:
|
|
|
|
1. **Experience** (`content/experience/`) - Job history with `jobTitle`, `company`, `location`, `duration`
|
|
2. **Skills** (`content/skills/`) - Technical skills with progress bars and categories
|
|
3. **Blog** (`content/blog/`) - Posts with sidebar/default layouts
|
|
4. **Client-work** (`content/client-work/`) - Portfolio pieces
|
|
5. **Testimonial** (`content/testimonial/`) - User testimonials
|
|
|
|
**Critical:** Each content type has a corresponding archetype in `archetypes/` and layout in `layouts/`. Always maintain this trio when adding new types.
|
|
|
|
## Development Workflows
|
|
|
|
### Local Development
|
|
```bash
|
|
# Install dependencies
|
|
npm install # Installs Bootstrap + theme-helper
|
|
# Theme development (testing with exampleSite)
|
|
npm run serve
|
|
```
|
|
|
|
### Testing
|
|
```bash
|
|
npm test # Full test suite
|
|
npm run test:e2e # Playwright E2E tests
|
|
npm run test:e2e:no-menus # Tests without navigation (for menu-less configs)
|
|
```
|
|
|
|
**Test Coverage:** E2E tests validate theme switching, language switching, content rendering, search functionality, and HTML validation across all major features.
|
|
|
|
### Performance Optimization
|
|
```bash
|
|
npm run build:performance # Optimized build with critical CSS
|
|
node scripts/optimize-performance.js # Performance analysis
|
|
```
|
|
|
|
## Styling System
|
|
|
|
**SCSS Architecture:** Modular approach extending Bootstrap 5
|
|
- `assets/scss/adritian.scss` - Main entry point importing all partials
|
|
- `assets/scss/_variables.scss` - Theme color/sizing variables
|
|
- Individual component files: `_navbar.scss`, `_blog.scss`, `_experience.scss`, etc.
|
|
|
|
**Theme Colors:** Uses CSS custom properties with `$base-color` as primary. Dark/light themes switch via CSS variables, not separate stylesheets.
|
|
|
|
## Multilingual (i18n) Implementation
|
|
|
|
**Translation Strategy:**
|
|
- Static strings: `i18n/*.yaml` files (navigation, UI elements)
|
|
- Content: Hugo's file-based translation (`content/en/`, `content/es/`, etc.)
|
|
- **Post-v1.7.0:** Prefers shortcode-based content over i18n strings for flexibility
|
|
|
|
## Shortcode System
|
|
|
|
**Primary Content Method:** Pages built with shortcodes rather than traditional Hugo sections.
|
|
|
|
Key shortcodes in `layouts/shortcodes/`:
|
|
- `experience-section` - Displays limited experience list (controlled by `homepageExperienceCount`)
|
|
- `experience-list` - Print-friendly experience list
|
|
- `contact-section` - Formspree integration
|
|
- `showcase-section` - Portfolio display
|
|
- `about-section`, `text-section` - Content blocks
|
|
|
|
**Pattern:** Most homepage sections use shortcodes for maximum customization flexibility.
|
|
|
|
## Module Distribution Model
|
|
|
|
**Critical Understanding:** This theme is distributed via:
|
|
1. **Hugo Module** (recommended) - `hugo mod get github.com/zetxek/adritian-free-hugo-theme`
|
|
2. **Theme Helper Package** - `@zetxek/adritian-theme-helper` downloads demo content
|
|
3. **Git Submodule** (legacy) - Direct theme inclusion
|
|
|
|
**Bootstrap Process:**
|
|
```bash
|
|
hugo mod get -u github.com/zetxek/adritian-free-hugo-theme
|
|
hugo mod npm pack
|
|
npm install # Installs Bootstrap + theme-helper
|
|
./node_modules/@zetxek/adritian-theme-helper/dist/scripts/download-content.js
|
|
```
|
|
|
|
## Configuration Patterns
|
|
|
|
**Hugo Config (`hugo.toml`):**
|
|
- Performance optimizations: `[minify]`, `[imaging]`, `[markup]` sections
|
|
- Custom output formats for content types (footer content excluded from HTML generation)
|
|
- Module imports section for theme loading
|
|
|
|
**Package.json Scripts:**
|
|
- `serve` - Development with exampleSite
|
|
- `build` - Production build with minification
|
|
- Separate test commands for different scenarios
|
|
|
|
## Key Integration Points
|
|
|
|
**Search:** Powered by Fuse.js with JSON index generation
|
|
**Contact Forms:** Formspree integration via shortcode
|
|
**Analytics:** Vercel Analytics support built-in
|
|
**Performance:** Critical CSS generation, image optimization, minification
|
|
|
|
## Common Development Pitfalls
|
|
|
|
1. **Missing Dependencies:** Theme requires Bootstrap via npm - users often miss `npm install` step
|
|
2. **Content Structure:** Custom content types require specific frontmatter fields - validate against archetypes
|
|
3. **Translation Scope:** Post-v1.7.0 prefers shortcode content over i18n strings
|
|
4. **Module vs Submodule:** Most issues stem from incorrect installation method
|
|
|
|
## Testing Philosophy
|
|
|
|
E2E tests validate real user workflows rather than individual components. Tests include theme switching, language switching, navigation, search, and content rendering across different configurations (with/without menus).
|
|
|
|
When modifying layouts or adding features, ensure corresponding E2E tests exist in `tests/e2e/`.
|
|
|
|
## Coding Standards and Conventions
|
|
|
|
### HTML/Hugo Templates
|
|
- Use semantic HTML5 elements for proper document structure
|
|
- Follow Hugo's template naming conventions (lowercase with hyphens)
|
|
- Partial templates should be in `layouts/partials/`
|
|
- Shortcodes should be in `layouts/shortcodes/`
|
|
- Use Hugo's built-in functions when available (e.g., `absURL`, `relURL`)
|
|
|
|
### SCSS/CSS
|
|
- Follow Bootstrap 5 conventions and utility classes where possible
|
|
- Use BEM naming methodology for custom components when needed
|
|
- Prefix custom variables with theme-specific identifiers
|
|
- Keep files modular - one component per file
|
|
- Use CSS custom properties for themeable values
|
|
- File naming: lowercase with underscores (e.g., `_navbar.scss`, `_blog.scss`)
|
|
|
|
### JavaScript
|
|
- Use vanilla JavaScript (no jQuery)
|
|
- Prefer modern ES6+ syntax
|
|
- Keep JavaScript minimal - theme is primarily CSS-driven
|
|
- Use DOMPurify for any user-generated content sanitization
|
|
- Ensure all JavaScript is progressively enhanced (works without JS when possible)
|
|
|
|
### Content and Configuration
|
|
- YAML frontmatter for content files
|
|
- TOML for Hugo configuration files
|
|
- Follow existing frontmatter patterns for each content type
|
|
- Use descriptive, human-readable keys
|
|
|
|
### File Naming Conventions
|
|
- Templates: lowercase with hyphens (e.g., `single.html`, `list.html`)
|
|
- SCSS files: lowercase with underscores, prefixed with `_` for partials
|
|
- Content files: lowercase with hyphens (e.g., `my-blog-post.md`)
|
|
- Archetypes: match content type name (e.g., `blog.md`, `experience.md`)
|
|
|
|
## Web Accessibility Requirements
|
|
|
|
**This theme prioritizes accessibility (WCAG 2.1 AA compliance):**
|
|
|
|
- All interactive elements must be keyboard accessible
|
|
- Proper ARIA labels and roles for non-semantic elements
|
|
- Color contrast ratios must meet WCAG AA standards (4.5:1 for normal text, 3:1 for large text)
|
|
- Images must have descriptive `alt` attributes
|
|
- Forms must have associated labels
|
|
- Focus indicators must be visible and clear
|
|
- Dark/light theme switching must maintain accessibility standards in both modes
|
|
- Skip navigation links for keyboard users
|
|
- Semantic HTML structure (proper heading hierarchy, landmarks, etc.)
|
|
- Test changes with screen readers when modifying navigation or interactive elements
|
|
|
|
## Security Best Practices
|
|
|
|
- Never commit secrets, API keys, or sensitive data
|
|
- Use DOMPurify for sanitizing any user-generated or external content
|
|
- Validate and sanitize all user inputs in contact forms
|
|
- Follow Hugo's security best practices for template rendering
|
|
- Keep dependencies updated to patch security vulnerabilities
|
|
- Use Hugo's built-in `safeHTML`, `safeCSS`, `safeJS` functions appropriately
|
|
|
|
## Files and Directories to Ignore
|
|
|
|
Copilot should **ignore** or be cautious with:
|
|
- `node_modules/` - Third-party dependencies
|
|
- `public/` - Hugo build output (generated files)
|
|
- `resources/` - Hugo's asset cache
|
|
- `.hugo_build.lock` - Hugo build lock file
|
|
- `package-lock.json` - npm lock file (only update via npm commands)
|
|
- `.git/` - Version control directory
|
|
- `exampleSite/public/` - Example site build output
|
|
- `exampleSite/resources/` - Example site cache
|
|
- `.DS_Store` - macOS system files |