Guide for developing with Hextra, a modern Hugo theme for documentation and static sites with Tailwind CSS
A comprehensive guide for working with Hextra, a modern Hugo theme designed for creating documentation websites, technical blogs, and static sites. Built with Tailwind CSS and inspired by Nextra, featuring full-text search, dark mode, multi-language support, and extensive customization.
You are working with a Hugo theme that requires:
1. **Start the development server with theme reloading:**
```bash
npm run dev:theme
# or using Task runner
task dev
```
2. **Build the example site:**
```bash
npm run build
# or
task build
```
3. **Compile CSS assets only:**
```bash
npm run build:css
# or
task css
```
Familiarize yourself with these key directories:
- Core UI: `navbar.html`, `sidebar.html`, `footer.html`, `breadcrumb.html`, `toc.html`
- Utilities: `layouts/_partials/utils/` for helper functions
- Custom overrides: `layouts/_partials/custom/` for user customizations
```
assets/
├── css/
│ ├── styles.css # Main stylesheet (source)
│ ├── compiled/main.css # Built CSS output (generated)
│ ├── components/ # Component-specific styles
│ └── chroma/ # Syntax highlighting themes
├── js/ # JavaScript components
└── lib/ # External libraries
```
1. **For layout modifications:**
- Edit files in `layouts/` directory
- Test specialized layouts in `layouts/docs/` or `layouts/blog/`
- Use `layouts/_partials/custom/` for site-specific customizations
2. **For CSS changes:**
- Edit `assets/css/styles.css` (main stylesheet)
- Component styles go in `assets/css/components/`
- CSS compiles via: Tailwind CSS → PostCSS → `assets/css/compiled/main.css`
- Run `npm run build:css` or `task css` to compile
3. **For JavaScript changes:**
- Core components in `assets/js/`: `theme.js`, `search.js`, `nav-menu.js`, `code-copy.js`
- Keep JavaScript minimal and performance-focused
4. **For content features:**
- Add shortcodes in `layouts/_shortcodes/`
- Modify Markdown rendering in `layouts/_markup/`
1. **Use the example site in `docs/` directory:**
- This serves as both documentation and testing ground
- Configuration example: `docs/hugo.yaml` shows multi-language setup
- Run from docs: `hugo server --themesDir=../..`
2. **Test multi-language functionality:**
- Translation files in `i18n/` (e.g., `en.yaml`, `fa.yaml`, `ja.yaml`, `zh-cn.yaml`)
- Example supports English, Persian (RTL), Japanese, Simplified Chinese
- Verify all supported languages render correctly
3. **Format code before committing:**
```bash
npx prettier --write .
```
Key files to understand:
1. **Follow Hugo conventions:**
- Theme files override Hugo defaults
- Maintain backward compatibility with existing configurations
- Follow Hugo's theme development guidelines
2. **Performance optimization:**
- Keep JavaScript minimal
- Use component-based CSS organization
- Leverage Tailwind CSS utilities
3. **Customization points:**
- Custom partials: `layouts/_partials/custom/`
- Custom CSS: `assets/css/custom.css`
- Site-specific overrides: Copy layouts to site's `layouts/` directory
4. **Development server:**
- Default port: 1313
- Runs with `--disableFastRender -D` for better development experience
- Theme development uses `--logLevel=debug` for detailed logging
1. Test all changes in `docs/` before releasing
2. Use `npm run dev:theme` for hot reloading during development
3. Verify responsive design across device sizes
4. Test dark/light mode switching
5. Validate multi-language support
6. Check SEO features (Open Graph, Twitter Cards, structured data)
1. Create file in `layouts/_shortcodes/your-shortcode.html`
2. Implement Hugo template logic
3. Document usage in `docs/content/docs/`
4. Test in example site
1. Edit `assets/css/styles.css` or component files
2. Run `npm run build:css` to compile
3. Test with `npm run dev:theme`
4. Verify dark mode compatibility
1. Create translation file in `i18n/your-language.yaml`
2. Update `docs/hugo.yaml` language configuration
3. Test all UI strings render correctly
4. Consider RTL support if applicable
1. Identify the layout file to modify
2. Copy to site's `layouts/` directory if needed
3. Make changes following Hugo template syntax
4. Test with development server
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/hextra-theme-development/raw