# Hugoplate Best Practices > 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. Use when this capability is needed. - Skill: `tomevault-io/hugoplate-best-practices` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/hugoplate-best-practices` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/hugoplate-best-practices/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/hugoplate-best-practices --- # 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. --- > Source: [sitepins/roxo-hugo](https://github.com/sitepins/roxo-hugo) — distributed by [TomeVault](https://tomevault.io).