Hextra Theme Development

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.

Project Context

You are working with a Hugo theme that requires:

Development Commands

Starting Development

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

```

Architecture Understanding

Hugo Theme File Structure

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

Asset Organization

```

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

```

Key Features

Development Workflow

Making Changes

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/`

Testing Changes

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 .

```

Configuration Files

Key files to understand:

Best Practices

Theme Development

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

Quality Assurance

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)

Common Tasks

Adding a New Shortcode

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

Modifying CSS

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

Adding Language Support

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

Customizing Layouts

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

Troubleshooting