f8b297eaad
* replace Bootstrap-based styling with Tailwind CSS * update theme compatibility for latest Hugo version * refactor templates and partials * fix outdated code and broken components * improve project structure and maintainability * optimize styling and frontend build setup
102 lines
5.0 KiB
Markdown
102 lines
5.0 KiB
Markdown
---
|
|
name: hugoplate-best-practices
|
|
description: Best practices and architectural patterns for working with the Hugoplate Hugo boilerplate. Use this when modifying theme tokens, configuration, content, layouts, or Tailwind v4 styles in a Hugoplate project.
|
|
license: MIT
|
|
---
|
|
|
|
# Hugoplate Agent Skill
|
|
|
|
This skill provides the best practices and architectural patterns for working with the **Hugoplate** boilerplate. Use this as your primary guide when modifying theme tokens, configuration, content, or layouts.
|
|
|
|
## 1. Core Architecture
|
|
|
|
Hugoplate is a modern Hugo boilerplate built with:
|
|
|
|
- **Hugo (Extended)**: Static site generator.
|
|
- **Tailwind CSS v4**: Utility-first CSS using Hugo Pipes and the `@theme` directive.
|
|
- **Hugo Modules**: Theme and feature functionality are imported as modules.
|
|
- **Theme Generator**: A custom Node.js script (`scripts/themeGenerator.js`) that syncs `data/theme.json` with Tailwind CSS variables.
|
|
|
|
## 2. Design System (`theme.json`)
|
|
|
|
All design tokens (colors, fonts, sizes) are managed in `exampleSite/data/theme.json`.
|
|
|
|
### 2.1 Color Tokens
|
|
|
|
- **Default (Light)**: `colors.default.theme_color` and `colors.default.text_color`.
|
|
- **Dark Mode**: `colors.darkmode.theme_color` and `colors.darkmode.text_color`.
|
|
- **Logic**: The `themeGenerator.js` script maps these to CSS variables (e.g., `--color-primary`, `--color-darkmode-primary`).
|
|
|
|
### 2.2 Typography
|
|
|
|
- **Google Fonts**: Defined in `fonts.font_family`. Use the syntax `Family:wght@weights` (e.g., `Inter:wght@400;700`).
|
|
- **Scale**: `fonts.font_size.scale` controls the heading hierarchy (H1-H6).
|
|
- **Base**: `fonts.font_size.base` sets the root font size in pixels.
|
|
|
|
### 2.3 Workflow: Design Changes
|
|
|
|
1. **Modify `theme.json`**: Update colors or fonts.
|
|
2. **Run Dev Server**: `npm run dev` or `yarn dev`. This automatically runs `themeGenerator.js` and `hugo server`.
|
|
3. **Verify**: Check `assets/css/generated-theme.css` to see the updated variables.
|
|
|
|
## 3. Configuration System
|
|
|
|
Configuration is split across several files in `exampleSite/config/_default/`:
|
|
|
|
- `hugo.toml`: Core site settings, build options, and asset fingerprinting.
|
|
- `params.toml`: Theme-specific toggles (dark mode, search, navigation, etc.).
|
|
- `menus.en.toml`: Menu structures for English.
|
|
- `languages.toml`: Multilingual setup.
|
|
- `module.toml`: Import declarations for Hugo Modules.
|
|
|
|
### 3.1 Feature Toggles (`params.toml`)
|
|
|
|
Most UI components (e.g., `preloader`, `announcement`, `cookies`) have an `enable` flag. Toggle them here without touching the code.
|
|
|
|
## 4. Content Development
|
|
|
|
Content is located in `exampleSite/content/english/`.
|
|
|
|
### 4.1 Section Content
|
|
|
|
Files in `content/english/sections/` are typically used for homepage sections. They often use `build.render = "never"` because they are pulled into `index.html` via `site.GetPage`.
|
|
|
|
### 4.2 Front Matter Standards
|
|
|
|
Always include `title`, `description` (for SEO), and `image` (feature image). Use `draft: false` to publish.
|
|
|
|
## 5. Layouts & Templates
|
|
|
|
- **Base**: `layouts/baseof.html` is the master wrapper.
|
|
- **Homepage**: `layouts/index.html` iterates through section files.
|
|
- **Partials**: Reusable fragments in `layouts/partials/`.
|
|
- **Overriding Modules**: To override a module partial, create a file with the same path in your local `layouts/` directory.
|
|
|
|
## 6. CSS & Tailwind Best Practices
|
|
|
|
- **Tailwind v4**: Uses `@theme` in `assets/css/main.css`. Avoid creating `tailwind.config.js` as it's not the primary way to configure v4 in this project.
|
|
- **Layers**: Add custom CSS to `assets/css/custom.css` or within `@layer` blocks in `main.css`.
|
|
- **Images**: Use the `partial "image"` for automatic Hugo responsive processing and WebP conversion.
|
|
|
|
## 7. Development Commands
|
|
|
|
| Command | Purpose |
|
|
| -------------------------- | ------------------------------------------------------ |
|
|
| `npm run dev` | Start dev server with theme watching. |
|
|
| `npm run build` | Production build with minification and fingerprinting. |
|
|
| `npm run update-modules` | Clean and update Hugo modules to latest. |
|
|
| `npm run remove-darkmode` | Permanently remove dark mode functionality. |
|
|
| `npm run remove-multilang` | Permanently remove multilingual support. |
|
|
|
|
## 8. Troubleshooting
|
|
|
|
- **Styles not updating**: Ensure `npm run dev` is running (it needs to regenerate `generated-theme.css`).
|
|
- **Classes missing**: Tailwind v4 in this project scans `hugo_stats.json`. If a new class isn't working, try a full rebuild.
|
|
- **Google Fonts error**: Check for spaces or incorrect weight syntax in `theme.json`.
|
|
|
|
## 9. AI Agent Guidelines
|
|
|
|
- **Always Read Context**: Before modifying a layout, check if a partial exists in `layouts/partials/essentials/` that might already handle it.
|
|
- **Prefer Tokens**: Never hardcode hex colors in CSS. Add them to `theme.json` and use the generated Tailwind classes.
|
|
- **Check Params**: Before writing logic to hide/show a section, check `params.toml` for an existing toggle.
|