Hextra Hugo Theme Development

This skill provides expert guidance for working with Hextra, a modern Hugo theme designed for documentation websites, technical blogs, and static sites. Built with Tailwind CSS and inspired by Nextra, it offers full-text search, dark mode, multi-language support, and extensive customization.

Project Overview

Hextra is a Hugo theme with:

Development Workflow

When working with this codebase, follow these steps:

1. Initial Setup Verification

2. Development Server

**Start the development server:**

```bash

npm run dev:theme

or

task dev

```

This runs the Hugo server with:

3. CSS Development

**CSS workflow:**

**Build CSS only:**

```bash

npm run build:css

or

task css

```

4. Building for Production

```bash

npm run build

or

task build

```

5. Code Quality

Before committing changes:

```bash

npx prettier --write .

```

Architecture Guidelines

Hugo Theme Structure

**Layouts hierarchy:**

- Core UI: `navbar.html`, `sidebar.html`, `footer.html`, `breadcrumb.html`, `toc.html`

- Utilities: `layouts/_partials/utils/`

- Custom overrides: `layouts/_partials/custom/`

**Shortcodes in `layouts/_shortcodes/`:**

**Render hooks in `layouts/_markup/`:**

Asset Organization

```

assets/

├── css/

│ ├── styles.css # Main stylesheet (edit this)

│ ├── compiled/main.css # Built output (generated)

│ ├── components/ # Component styles

│ ├── chroma/ # Syntax highlighting themes

│ └── custom.css # User customizations

├── js/ # Core JavaScript

│ ├── theme.js

│ ├── search.js

│ ├── flexsearch.js

│ ├── nav-menu.js

│ └── code-copy.js

└── lib/ # External libraries

```

Key Components

**Search system:**

**Internationalization:**

**Theme features:**

Customization Points

For Theme Users (Customizing the Theme)

To customize Hextra in your site:

1. Copy layouts to your site's `layouts/` directory to override

2. Use `layouts/_partials/custom/` for custom partials

3. Add site-specific CSS in `assets/css/custom.css`

For Theme Developers (Modifying Core)

When modifying theme files:

Testing Strategy

**Before releasing changes:**

1. Test in `docs/` directory (example site)

2. Verify multi-language functionality

3. Test dark/light mode switching

4. Check responsive design across breakpoints

5. Validate search functionality

6. Run `npx prettier --write .` for formatting

**Development server with hot reloading:**

```bash

npm run dev:theme

```

**Test from docs directory:**

```bash

cd docs

hugo server --themesDir=../..

```

Configuration Files

**Key files to understand:**

Important Constraints

1. **Hugo Version:** Minimum 0.146.0 extended version required

2. **Go Version:** 1.20+ required

3. **Node.js:** Required for CSS compilation (PostCSS, Tailwind CSS v4+)

4. **Backward Compatibility:** Always maintain compatibility with existing configurations

5. **Performance:** Keep JavaScript minimal, optimize CSS output

6. **Accessibility:** Maintain semantic HTML and ARIA attributes

Common Tasks

**Add a new shortcode:**

1. Create file in `layouts/_shortcodes/[name].html`

2. Test in `docs/content/` with example usage

3. Document in theme documentation

**Modify CSS styling:**

1. Edit `assets/css/styles.css` or component files

2. Run `npm run build:css` to compile

3. Test with `npm run dev:theme`

**Add language translation:**

1. Create/edit file in `i18n/[lang-code].yaml`

2. Add language configuration in `hugo.yaml`

3. Test with multi-language example site

**Create custom partial:**

1. Add file to `layouts/_partials/custom/`

2. Include in templates where needed

3. Document customization point

Resources