gokrazy/website/themes/hugo-theme-relearn/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview

Hugo Relearn Theme is a documentation theme for Hugo, forked from the Learn theme. It's designed for creating documentation sites with features like multilingual support, dark mode, search, print support, and extensive shortcodes.

Minimum Hugo version required can be found in theme.toml.

Development Commands

Running the Theme

Development uses the docs for manual testing and documenting new features.

# Run the dev server from exampleSite directory
cd exampleSite
hugo server -p 1414

Development uses the exampleSite for manual testing and providing a simple showcase. The goal is to keep configuration minimal and be a first starting point for new users.

# Run the dev server from exampleSite directory
cd exampleSite
hugo server

Configurations

During development cycles, the server is started manually without an environment option.

The following other environments are available:

• testing - used to test the site during development using test-hugo.bat
• github - used to release the site on GitHub Pages
• dev - used to generate the site similar to GitHub Pages but usable locally
• performance - disables all performance intensive features to make building as fast as possible
• versioning - used to manually test the versioning feature

Building

# Build from docs
cd docs
hugo

# Build with minification (production)
hugo --minify

Screenshots Tool

# Generate screenshots using Puppeteer
cd tools
npm install
npm run screenshots

Architecture

Directory Structure

• layouts/ - Hugo templates organized by type

  • _default/ - Base layouts (baseof.html, single.html, list.html, etc.)
  • partials/ - Reusable template partials
    • _relearn/ - Core theme helper functions (.gotmpl files)
  • shortcodes/ - Theme shortcodes (badge, button, card, tabs, mermaid, etc.)
  • chapter/, home/ - Specialized page layouts

• assets/ - Source files processed by Hugo Pipes

  • css/ - Stylesheets including theme variants and chroma syntax highlighting
  • js/ - JavaScript modules (theme.js, search, clipboard, etc.)

• i18n/ - Translation files (.toml) for 26+ languages

• archetypes/ - Content templates (default.md, chapter.md, home.md)

• exampleSite/ - Full demo site used for development

  • config/_default/ - Base configuration
  • config/testing/, config/github/, etc. - Environment-specific configs

• docs/ - Documentation site source (separate from exampleSite)

  • config/_default/ - Base configuration
  • config/testing/, config/github/, etc. - Environment-specific configs

Key Template Concepts

Partials in layouts/partials/_relearn/:

• .gotmpl extension indicates Hugo template functions
• Core utilities: boxStyle, decoratedLink, imageAttributes, linkAttributes, menuObject, dependencies
• These are helper functions, not rendered partials

Shortcodes:

• Highly modular - each shortcode in layouts/shortcodes/
• Support both inline and block syntax
• Examples: badge, button, card/cards, expand, icon, include, math, mermaid, notice, openapi, tab/tabs, tree

Dependencies System:

• Theme uses a dependency loading system defined in hugo.toml under params.relearn.dependencies
• Dependencies: Math, Mermaid, OpenApi, Search, Theme
• Loaded on-demand based on shortcode usage

Output Formats

Theme supports custom output formats:

• print - Printable versions of pages
• source - Markdown source view
• Define in hugo.toml under [outputFormats]

Theming System

Color Variants:

• Multiple built-in variants in assets/css/theme-*.css
• Variants: relearn-light, relearn-dark, relearn-bright, learn, neon, blue, green, red, zen-light, zen-dark
• Users can switch variants via the topbar
• Base theme variables in assets/css/variables.css

Chroma Syntax Highlighting:

• Separate chroma stylesheets for each variant: chroma-*.css

Search Implementation

• Two search engines supported: Lunr and Orama
• Search files in assets/js/search*.js
• Search index generated at build time via _relearn_searchindex.js

JavaScript Architecture

• theme.js - Main theme JavaScript
• Modular dependencies loaded from subdirectories:
  • auto-complete/ - Search autocomplete
  • clipboard/ - Copy-to-clipboard
  • lunr/, orama/ - Search engines
  • mathjax/, mermaid/, d3/ - Feature libraries
  • perfect-scrollbar/ - Scrollbar customization

Code Quality Standards

Commit Message Format

Use conventional commit format.

Common commit types:

• Common: build, browser, chore, docs, shortcodes, theme
• Features: a11y, archetypes, alias, generator, i18n, mobile, print, rss, variant
• Structure: favicon, search, menu, history, scrollbar, nav, toc, clipboard, syntaxhighlight, boxes
• Shortcodes: attachments, badge, button, children, expand, icon, include, math, mermaid, notice, openapi, piratify, siteparam, tabs

Example: search: improve Orama integration for multilingual sites

Development Principles

• Convention over configuration - Site should work with minimal configuration
• Stay close to Hugo - Follow Hugo patterns and conventions
• No build tools - Avoid npm/preprocessing for theme itself (contributors may not be front-end developers)
• Document features - New features require documentation and release notes entries
• Backwards compatibility - Don't break existing features unless necessary
• Clean output - Remove console errors, check HTML whitespace and indentation

Git Hooks

Python-based git hooks in .githooks/:

• post-commit.py - Post-commit processing
• pre-push.py - Pre-push validation

Important Files

• hugo.toml - Theme configuration and module requirements
• theme.toml - Theme metadata (name, features, Hugo version)
• go.mod - Hugo module definition
• .prettierrc.json / .prettierignore - Code formatting (Prettier)
• .editorconfig - Editor configuration
• CHANGELOG.md - Detailed version history

Content Development

Front Matter

Standard front matter for content:

+++
title = "Page Title"
weight = 10  # Ordering in sidebar
+++

Page Types

• Home - Site landing page (uses layouts/home/)
• Chapter - Section pages (uses layouts/chapter/)
• Default - Regular content pages

Multilingual Sites

• Translation files in i18n/*.toml
• Content organized by language code: content/en/, content/de/, etc.
• Set defaultContentLanguage in hugo.toml

Testing

Test against the exampleSite which demonstrates all theme features. Verify:

• Search functionality (both Lunr and Orama)
• Print output
• Theme variant switching
• Shortcodes rendering
• Mobile responsiveness
• Multilingual navigation
• No console errors

Release Process

Releases happen directly from the main branch without prior notice. Every commit to main must be production-ready and result in a releasable version.