Init Commit
This commit is contained in:
+214
@@ -0,0 +1,214 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user