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 for local tool and task management

Use the theme

Nerdy is intended to be used as a Hugo Module:

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

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

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:

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

Then open https://nerdy.localhost.

Portless 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:

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

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:

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.