Makefile Reference

Complete reference for all Makefile commands available in this Hugo theme.

The theme includes a comprehensive Makefile that automates development workflows, testing, and deployment processes. This guide covers all available commands and their use cases.

Quick Reference #

Get help on all available commands:

bash

make help

Development Commands #

Starting Development Servers #

Start a development server with different theme variants:

bash

# Default variant (theme development)
make dev

# With debug mode enabled  
make dev-debug

# Specific theme variants (theme development)
make dev-nvidia       # NVIDIA branding
make dev-opensource   # Open source styling
make dev-enterprise   # Enterprise styling

# External theme testing
make dev-external     # Test as external theme dependency

What happens:

Starts Hugo development server on http://localhost:1313
Enables live reload for instant preview of changes
Uses development environment (unminified assets)
Debug variants enable template debugging panel

Important: Development commands (make dev-*) include --themesDir ../.. because the exampleSite is nested within the theme repository. Use make dev-external when the theme is installed as an external dependency.

Theme Variant Testing #

Test specific theme configurations:

bash

make dev-nvidia       # Test NVIDIA variant
make dev-opensource   # Test Open Source variant  
make dev-enterprise   # Test Enterprise variant

Each variant loads:

Variant-specific configuration from config/{variant}/
Brand-specific fonts, colors, and styling
Customized logos and organization details

Production Commands #

Building for Production #

Create optimized production builds:

bash

# Build specific variants
make build-default      # Default variant
make build-nvidia       # NVIDIA variant
make build-opensource   # Open Source variant
make build-enterprise   # Enterprise variant

Production optimizations:

Asset minification and compression
CSS/JS bundling and fingerprinting
Image optimization
SEO enhancements

Offline Documentation #

Build standalone documentation packages:

bash

make offline          # Production offline build
make offline-drafts   # Include draft content

Output:

Creates offline-docs.tar.gz containing complete site
Compatible with file:// protocol for air-gapped environments
Includes all assets and dependencies

Testing & Quality Assurance #

Comprehensive Testing #

Test all theme variants:

bash

make test-all-variants

What it tests:

Build success for all variants
Configuration validity
Template compilation
Asset pipeline

Debug Information #

Get system information:

bash

make debug-info

Provides:

Hugo version and build information
Module dependency graph
Configuration validation

API Documentation #

OpenAPI Integration #

Generate REST API documentation from OpenAPI specifications:

bash

# Custom specification
make api-gen INPUT=your-spec.yaml OUTPUT=processed.json

# Test with example
make api-gen-test

Process:

Runs tools/spec-preprocessor.py script
Resolves component references
Generates theme-compatible JSON
Ready for use with layout: api

Usage in content:

yaml

---
title: "API Reference"
layout: api
reference: "processed"  # References /data/processed.json
---

Version Management #

Release Management #

Update version information across documentation:

bash

make v-bump P=product_name VDIR=version_dir V=version_number

Updates:

Product release frontmatter
Supported release tables
Version-specific configurations

Configuration Examples #

Environment-Specific Builds #

The Makefile properly separates Hugo environments from theme variants:

bash

# Development with NVIDIA branding
make dev-nvidia

# Production build with NVIDIA branding  
make build-nvidia

# Debug mode with any variant
make dev-debug

Custom Configurations #

Override default behavior:

bash

# Custom config combination
hugo server --config config/_default,config/nvidia,config/custom

# Environment override
HUGO_ENVIRONMENT=production make dev-nvidia

Development Setup Scenarios #

Scenario 1: Theme Development (Nested exampleSite)

bash

# You're working inside the theme repository
cd path/to/milodocs/exampleSite
make dev-nvidia  # Uses --themesDir ../..

Scenario 2: External Theme Usage

bash

# You're using the theme as a dependency
cd your-hugo-site
make dev-external  # No --themesDir needed

Scenario 3: Custom Hugo Commands

bash

# Manual commands for theme development
hugo server --config config/_default,config/nvidia --themesDir ../..

# Manual commands for external usage
hugo server --config config/_default,config/nvidia

Workflow Integration #

Recommended Development Flow #

Start with debug mode:
bash
```
make dev-debug
```
Test specific variants:
bash
```
make dev-nvidia
make dev-opensource  
```
Validate before deployment:
bash
```
make test-all-variants
```

Build for production:

bash

make build-nvidia  # or your target variant

CI/CD Integration #

Example GitHub Actions workflow:

yaml

- name: Test all variants
  run: make test-all-variants
  
- name: Build production
  run: make build-enterprise
  
- name: Create offline package  
  run: make offline

Source code #

bash

# Makefile for Hugo theme development and variant testing

# Default development server (default theme variant)
dev default:
	@echo "Starting Hugo development server (default variant)"
	@hugo server --themesDir ../..

# Development with debug mode enabled
dev-debug:
	@echo "Starting Hugo development server with debug mode"
	@hugo server -D --themesDir ../..

# Theme Variant Development Servers
dev-nvidia:
	@echo "Starting Hugo development server (NVIDIA variant)"
	@hugo server --configDir config --environment nvidia --themesDir ../..

dev-opensource:
	@echo "Starting Hugo development server (Open Source variant)"  
	@hugo server --configDir config --environment open-source --themesDir ../..

dev-enterprise:
	@echo "Starting Hugo development server (Enterprise variant)"
	@hugo server --configDir config --environment enterprise --themesDir ../..

# Development server with custom themes directory (for external theme testing)
dev-external:
	@echo "Starting Hugo development server (external theme mode)"
	@hugo server

# Production builds for different variants
build-nvidia:
	@echo "Building NVIDIA variant for production"
	@hugo --configDir config --environment nvidia --themesDir ../.. --minify

build-opensource:
	@echo "Building Open Source variant for production"
	@hugo --configDir config --environment open-source --themesDir ../.. --minify

build-enterprise:
	@echo "Building Enterprise variant for production"
	@hugo --configDir config --environment enterprise --themesDir ../.. --minify

build-default:
	@echo "Building default variant for production"
	@hugo --environment production --themesDir ../.. --minify

# Target for generating the OpenAPI spec for the API reference

api-gen:
	python tools/spec-preprocessor.py $(INPUT) $(OUTPUT)

api-gen-test:
	python tools/spec-preprocessor.py data/basicApi.yaml data/basicApi-output.json 

# Offline builds
offline-drafts:
	@echo "Building Hugo site for offline use with drafts"
	@hugo -D --configDir config --environment offline --themesDir ../.. --minify
	@tar -czvf offline-docs.tar.gz ./public
	@echo "Site packaged into offline-docs.tar.gz (including drafts)"

offline:
	@echo "Building Hugo site for offline use"
	@hugo --configDir config --environment offline --themesDir ../.. --minify
	@tar -czvf offline-docs.tar.gz ./public
	@echo "Site packaged into offline-docs.tar.gz"

# Debug and testing commands
debug-info:
	@echo "Checking Hugo version and module information"
	@hugo version
	@hugo mod graph

test-all-variants:
	@echo "Testing all theme variants..."
	@echo "Testing default variant..."
	@hugo --configDir config --themesDir ../.. --quiet || echo "❌ Default variant failed"
	@echo "Testing NVIDIA variant..."
	@hugo --configDir config --environment nvidia --themesDir ../.. --quiet || echo "❌ NVIDIA variant failed"
	@echo "Testing Open Source variant..."
	@hugo --configDir config --environment open-source --themesDir ../.. --quiet || echo "❌ Open Source variant failed"
	@echo "Testing Enterprise variant..."
	@hugo --configDir config --environment enterprise --themesDir ../.. --quiet || echo "❌ Enterprise variant failed"
	@echo "✅ All variants tested"

# Help command
help:
	@echo "Hugo Theme Development Commands:"
	@echo ""
	@echo "Development Servers (Theme Development):"
	@echo "  make dev              - Start default variant development server"
	@echo "  make dev-debug        - Start development server with debug mode"
	@echo "  make dev-nvidia       - Start NVIDIA variant development server"
	@echo "  make dev-opensource   - Start Open Source variant development server"
	@echo "  make dev-enterprise   - Start Enterprise variant development server"
	@echo "  make dev-external     - Start server for external theme testing"
	@echo ""
	@echo "Note: Dev commands use --themesDir ../.. for nested theme development"
	@echo ""
	@echo "Production Builds:"
	@echo "  make build-default    - Build default variant for production"
	@echo "  make build-nvidia     - Build NVIDIA variant for production"
	@echo "  make build-opensource - Build Open Source variant for production"
	@echo "  make build-enterprise - Build Enterprise variant for production"
	@echo ""
	@echo "Offline Builds:"
	@echo "  make offline         - Build offline version (no drafts)"
	@echo "  make offline-drafts  - Build offline version (with drafts)"
	@echo ""
	@echo "Testing & Debug:"
	@echo "  make debug-info      - Show Hugo version and module info"
	@echo "  make test-all-variants - Test build all theme variants"
	@echo ""
	@echo "API Tools:"
	@echo "  make api-gen INPUT=file.yaml OUTPUT=file.json - Generate API spec"
	@echo "  make api-gen-test    - Test API generation"
	@echo ""
	@echo "Version Management:"
	@echo "  make v-bump P=product VDIR=version V=number - Update version frontmatter"

# Target for updating the release frontmatter for a given product vdir; also updates the supported release table csv
## # Usage: make update-frontmatter P=<product_name> VDIR=<version_dir> V=<new_version_number>
v-bump:
	@python tools/update-prod-release-frontmatter.py $(P) $(VDIR) $(V)
	@python tools/update-supported-release-table.py $(P) $(V)

Article Summarization

Quick Reference #

Development Commands #

Starting Development Servers #

Theme Variant Testing #

Production Commands #

Building for Production #

Offline Documentation #

Testing & Quality Assurance #

Comprehensive Testing #

Debug Information #

API Documentation #

OpenAPI Integration #

Version Management #

Release Management #

Configuration Examples #

Environment-Specific Builds #

Custom Configurations #

Development Setup Scenarios #

Workflow Integration #

Recommended Development Flow #

CI/CD Integration #

Source code #