nerdy — Hugo Starter Template

SHA-256: a7922558654cd2955a4750db63fa2a86a328025355276cd6ddab197922c43ade

2026-10-03T07:28:35.803Z

# Nerdy

Nerdy is a nerd-vibed Hugo theme for personal portfolios and blogs.

**Live demo and documentation:** <https://nerdy.hugo-themes.com>

The demo site also serves as the documentation site.

## Features

- Nerd-vibed design.
- Interactive terminal for exploring the author.
- Card-style sidebar for an at-a-glance author overview.
- Group posts by subject, topic, and series.
- Data-driven configuration.
- Light and dark theme.

## Requirements

- Hugo `0.162.1` or newer
- Node.js 24 or newer and npm for Tailwind CSS, Portless, and JavaScript dependencies
- Go for Hugo Modules; the example site and recommended install path both use them
- Optional: [mise](https://mise.jdx.dev/) for local tool and task management

## Use the theme

Nerdy is intended to be used as a Hugo Module:

```yaml
module:
  imports:
    - path: github.com/hugo-themes/nerdy
```

Enable Hugo build stats so Tailwind can discover classes generated by Hugo templates:

```yaml
build:
  buildStats:
    enable: true
```

Your site also needs the npm dependencies used by the theme's asset pipeline. The dependencies in this repository's `package.json` are the reference set.

For the full setup flow, required data files, and customization options, use the documentation posts at <https://nerdy.hugo-themes.com>.

## Run locally

Clone the repository and run the bundled example site:

```sh
git clone https://github.com/hugo-themes/nerdy.git
cd nerdy
npm install
npm run server
```

Then open <https://nerdy.localhost>.

[Portless](https://portless.sh/) is installed as a development dependency and provides the stable local DNS name. On first run, it may ask to trust its local HTTPS certificate. If your browser still marks the page as not secure, run `npm run portless:trust`, restart the browser, and open `https://nerdy.localhost` again.

If `https://nerdy.localhost` shows a Portless 404, stop any stale Portless proxy with `portless proxy stop`, then run `npm run server` again. If the proxy was started with elevated privileges, use `sudo portless proxy stop` once before restarting.

To bypass Portless and run Hugo directly instead:

```sh
npm run server:local
```

Then open <http://localhost:1313>.

The repository root contains the reusable theme. The demo and documentation site lives in `exampleSite/` and is what the local server runs.

## Build locally

```sh
npm run build
```

The generated site is written to `exampleSite/public/`.

Use the npm scripts instead of calling `hugo` directly. They add `node_modules/.bin` to `PATH` and run a lightweight in-memory Hugo pass first so `hugo_stats.json` exists before Tailwind compiles the final stylesheet.

## npm scripts

| Command                | Description                                                                    |
| ---------------------- | ------------------------------------------------------------------------------ |
| `npm run server`       | Start the example/documentation site through Portless at `https://nerdy.localhost`. |
| `npm run dev`          | Alias for `npm run server`.                                                    |
| `npm run server:local` | Start the example/documentation site directly on `http://localhost:1313`.      |
| `npm run build`        | Build the production example/documentation site.                               |

## Optional mise workflow

If you use mise, the repository includes matching tasks:

```sh
mise install
mise run server
mise run build
```

`mise run server` uses the same Portless-backed flow as `npm run server`. Use `mise run server-local` to bypass Portless and serve directly on `http://localhost:1313`.

The mise tasks install npm dependencies automatically before running server or build commands.

## Project layout

- `layouts/` - theme templates and partials
- `assets/` - CSS, JavaScript, icons, and images processed by Hugo Pipes
- `exampleSite/` - live demo, documentation posts, sample content, and sample data
- `package.json` - Tailwind, Alpine.js, and local development scripts

## License

Nerdy is released under the [MIT License](LICENSE).