Step-by-Step Guide to Building a Technical Blog as a Senior Engineer with Hugo 0.120 and Netlify 2026

#!/bin/bash
# setup-local-env.sh
# Author: Senior Engineer (15y exp)
# Description: Automated local environment setup for Hugo 0.120 + Netlify 2026 blog
# Requires: macOS/Linux, curl, git

set -euo pipefail  # Exit on error, undefined vars, pipe failures

# Configuration
HUGO_VERSION=\"0.120.0\"
NETLIFY_CLI_VERSION=\"17.34.0\"
BLOG_REPO=\"https://github.com/yourusername/tech-blog-hugo-2026\"  # Replace with your repo
LOCAL_PORT=1313
BUILD_DIR=\"public\"

# Function to print colored logs
log_info() {
  echo -e \"\\033[0;34m[INFO] $1\\033[0m\"
}

log_error() {
  echo -e \"\\033[0;31m[ERROR] $1\\033[0m\"
}

log_success() {
  echo -e \"\\033[0;32m[SUCCESS] $1\\033[0m\"
}

# Check if required tools are installed
check_dependency() {
  local cmd=$1
  local install_msg=$2
  if ! command -v \"$cmd\" &> /dev/null; then
    log_error \"Missing dependency: $cmd\"
    log_info \"Install via: $install_msg\"
    exit 1
  fi
}

log_info \"Starting local environment setup for Hugo ${HUGO_VERSION} + Netlify ${NETLIFY_CLI_VERSION}\"

# Check base dependencies
check_dependency \"git\" \"apt install git (Linux) / brew install git (macOS)\"
check_dependency \"curl\" \"apt install curl (Linux) / brew install curl (macOS)\"

# Install Hugo 0.120.0 (exact version to avoid breaking changes)
log_info \"Checking Hugo installation...\"
if command -v hugo &> /dev/null; then
  CURRENT_HUGO=$(hugo version | grep -oP 'v\\K[0-9.]+')
  if [ \"$CURRENT_HUGO\" != \"$HUGO_VERSION\" ]; then
    log_info \"Upgrading Hugo from $CURRENT_HUGO to $HUGO_VERSION\"
    # Install via hugo installer script (adjust for macOS: hugo_${HUGO_VERSION}_darwin-universal.tar.gz)
    curl -sSL https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_${HUGO_VERSION}_linux-amd64.tar.gz -o /tmp/hugo.tar.gz
    tar -xzf /tmp/hugo.tar.gz -C /tmp/
    sudo mv /tmp/hugo /usr/local/bin/hugo
    rm /tmp/hugo.tar.gz
  else
    log_info \"Hugo $HUGO_VERSION already installed\"
  fi
else
  log_info \"Installing Hugo $HUGO_VERSION...\"
  curl -sSL https://github.com/gohugoio/hugo/releases/download/v${HUGO_VERSION}/hugo_${HUGO_VERSION}_linux-amd64.tar.gz -o /tmp/hugo.tar.gz
  tar -xzf /tmp/hugo.tar.gz -C /tmp/
  sudo mv /tmp/hugo /usr/local/bin/hugo
  rm /tmp/hugo.tar.gz
fi

# Verify Hugo installation
if ! hugo version | grep -q \"v${HUGO_VERSION}\"; then
  log_error \"Hugo installation failed. Expected version $HUGO_VERSION\"
  exit 1
fi
log_success \"Hugo $HUGO_VERSION installed successfully\"

# Install Netlify CLI
log_info \"Checking Netlify CLI installation...\"
if command -v netlify &> /dev/null; then
  CURRENT_NETLIFY=$(netlify --version | grep -oP '\\K[0-9.]+')
  if [ \"$CURRENT_NETLIFY\" != \"$NETLIFY_CLI_VERSION\" ]; then
    log_info \"Upgrading Netlify CLI from $CURRENT_NETLIFY to $NETLIFY_CLI_VERSION\"
    npm install -g netlify-cli@${NETLIFY_CLI_VERSION}
  else
    log_info \"Netlify CLI $NETLIFY_CLI_VERSION already installed\"
  fi
else
  log_info \"Installing Netlify CLI $NETLIFY_CLI_VERSION...\"
  npm install -g netlify-cli@${NETLIFY_CLI_VERSION}
fi

# Verify Netlify CLI
if ! netlify --version | grep -q \"$NETLIFY_CLI_VERSION\"; then
  log_error \"Netlify CLI installation failed. Expected version $NETLIFY_CLI_VERSION\"
  exit 1
fi
log_success \"Netlify CLI $NETLIFY_CLI_VERSION installed successfully\"

# Clone or initialize blog repo
if [ ! -d \"tech-blog-hugo-2026\" ]; then
  log_info \"Cloning blog repo from $BLOG_REPO...\"
  git clone \"$BLOG_REPO\" tech-blog-hugo-2026 || {
    log_info \"Repo not found, initializing new Hugo site...\"
    hugo new site tech-blog-hugo-2026 --format yaml
    cd tech-blog-hugo-2026
    git init
    git remote add origin \"$BLOG_REPO\"
  }
else
  log_info \"Blog repo already exists, pulling latest changes...\"
  cd tech-blog-hugo-2026
  git pull origin main
fi

# Install recommended Hugo theme (PaperMod 1.36, compatible with Hugo 0.120)
log_info \"Installing PaperMod theme...\"
cd tech-blog-hugo-2026
if [ ! -d \"themes/PaperMod\" ]; then
  git submodule add https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod --depth 1
  git submodule update --init --recursive
else
  log_info \"PaperMod theme already installed\"
fi

# Start local dev server to verify setup
log_info \"Starting local Hugo dev server on port $LOCAL_PORT...\"
hugo server -D --port \"$LOCAL_PORT\" --bind 0.0.0.0 &
SERVER_PID=$!

# Wait for server to start
sleep 5
if curl -s \"http://localhost:$LOCAL_PORT\" | grep -q \"Hugo\"; then
  log_success \"Local dev server running at http://localhost:$LOCAL_PORT\"
else
  log_error \"Local dev server failed to start\"
  kill $SERVER_PID 2>/dev/null
  exit 1
fi

log_success \"Local environment setup complete. Stop server with: kill $SERVER_PID\"

# config.yaml
# Hugo 0.120.0 configuration for senior engineering technical blog
# Optimized for 500+ posts, code-heavy content, and Netlify 2026 deployment

baseURL: \"https://yourusername-tech-blog.netlify.app/\"  # Replace with your Netlify URL
languageCode: \"en-us\"
title: \"Senior Engineering Bytes\"
theme: \"PaperMod\"
enableInlineShortcodes: true
enableRobotsTXT: true
buildDrafts: false
buildFuture: false
buildExpired: false
pygmentsCodeFences: true  # Enable code blocks with Chroma highlighting
pygmentsUseClasses: true  # Use CSS classes for highlighting (smaller HTML output)
pygmentsOptions: \"linenos=table,hl_lines=1-3,lineanchors=code\"  # Line numbers, highlight lines, anchors

# Content configuration
contentDir: \"content\"
dataDir: \"data\"
i18nDir: \"i18n\"
layoutDir: \"layouts\"
staticDir: \"static\"
assetDir: \"assets\"

# Taxonomies (custom for technical blogs)
taxonomies:
  tag: \"tags\"  # Default tag taxonomy
  category: \"categories\"  # Default category taxonomy
  series: \"series\"  # Custom series taxonomy for multi-part tutorials
  tool: \"tools\"  # Custom tool taxonomy (e.g., hugo, netlify, kubernetes)
  language: \"languages\"  # Custom language taxonomy (e.g., go, rust, python)

# Permalink structure (SEO-friendly, date-based)
permalinks:
  posts: \"/:year/:month/:day/:slug/\"
  guides: \"/guides/:slug/\"
  notes: \"/notes/:slug/\"

# Menu configuration
menu:
  main:
    - identifier: \"posts\"
      name: \"Posts\"
      url: \"/posts/\"
      weight: 1
    - identifier: \"guides\"
      name: \"Guides\"
      url: \"/guides/\"
      weight: 2
    - identifier: \"notes\"
      name: \"Notes\"
      url: \"/notes/\"
      weight: 3
    - identifier: \"about\"
      name: \"About\"
      url: \"/about/\"
      weight: 4
    - identifier: \"rss\"
      name: \"RSS\"
      url: \"/index.xml\"
      weight: 5

# Output formats (RSS, JSON for search)
outputFormats:
  rss:
    mediatype: \"application/rss+xml\"
    baseName: \"index\"
  json:
    mediatype: \"application/json\"
    baseName: \"search\"

# Media types
mediaTypes:
  \"application/json\":
    suffixes: [\"json\"]

# Security configuration (prevent malicious content)
security:
  enableInlineShortcodes: false  # Disable inline shortcodes for untrusted content
  exec:
    allow:
      - \"git\"
      - \"hugo\"
    deny:
      - \"rm\"
      - \"sudo\"
  funcs:
    getenv:
      allow:
        - \"HUGO_ENV\"
        - \"NETLIFY_ENV\"

# Imaging configuration (optimize images for web)
imaging:
  bgColor: \"#ffffff\"
  quality: 85
  resampleFilter: \"lanczos\"
  anchor: \"smart\"
  sizes:
    - \"320\"
    - \"640\"
    - \"1024\"
    - \"1920\"
  formats:
    - \"webp\"
    - \"avif\"
    - \"jpeg\"

# Sitemap configuration
sitemap:
  changefreq: \"weekly\"
  priority: 0.5
  filename: \"sitemap.xml\"

# RSS configuration
rssLimit: 20  # Only include last 20 posts in RSS
rssFullText: false  # Only include excerpt in RSS, not full post

# Pagination
pagination:
  pagerSize: 10  # 10 posts per page

# Markup configuration (code highlighting, Goldmark for Markdown)
markup:
  goldmark:
    renderer:
      unsafe: false  # Disable unsafe HTML in Markdown (prevent XSS)
    extensions:
      typographer: true  # Enable smart quotes, dashes
      linkify: true  # Auto-link URLs
      strikethrough: true
      subscript: true
      superscript: true
  highlight:
    style: \"dracula\"  # Code highlighting style (matches common terminal themes)
    lineNos: true
    lineNumbersInTable: true
    anchorLineNos: true
    guessSyntax: true  # Guess syntax for code blocks without language specified

# Netlify 2026 specific configuration (headers, redirects)
netlify:
  headers:
    - path: \"/*\"
      headers:
        - name: \"X-Frame-Options\"
          value: \"DENY\"
        - name: \"X-Content-Type-Options\"
          value: \"nosniff\"
        - name: \"Referrer-Policy\"
          value: \"strict-origin-when-cross-origin\"
        - name: \"Content-Security-Policy\"
          value: \"default-src 'self'; script-src 'self' 'unsafe-inline' https://plausible.io; style-src 'self' 'unsafe-inline'; img-src 'self' https://*; font-src 'self';\"
    - path: \"/admin/*\"
      headers:
        - name: \"Cache-Control\"
          value: \"no-cache\"
  redirects:
    - from: \"/old-blog/*\"
      to: \"/posts/:splat\"
      status: 301
    - from: \"/feed\"
      to: \"/index.xml\"
      status: 301

# netlify.toml
# Netlify 2026 configuration for Hugo 0.120 technical blog
# Optimized for incremental builds, edge caching, and zero cold starts

[build]
  command = \"hugo --gc --minify --baseURL $DEPLOY_URL\"  # GC unused resources, minify output
  publish = \"public\"  # Hugo's default build directory
  environment = { HUGO_VERSION = \"0.120.0\", HUGO_ENV = \"production\" }  # Pin Hugo version

# Incremental build configuration (Netlify 2026 feature)
[build.incremental]
  enable = true
  cache = [\"resources/_gen\", \"themes/PaperMod\"]  # Cache generated resources and theme

# Edge function for dynamic comment submission (Netlify 2026 edge runtime)
[[edge_functions]]
  path = \"/api/comments\"
  function = \"comments\"
  excluded_paths = [\"/admin/*\"]

# Headers for all requests
[[headers]]
  for = \"/*\"
  [headers.values]
    X-Frame-Options = \"DENY\"
    X-Content-Type-Options = \"nosniff\"
    Referrer-Policy = \"strict-origin-when-cross-origin\"
    Strict-Transport-Security = \"max-age=63072000; includeSubDomains; preload\"
    Content-Security-Policy = \"default-src 'self'; script-src 'self' https://plausible.io https://cdn.jsdelivr.net; style-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net; img-src 'self' https://* data:; font-src 'self' https://cdn.jsdelivr.net; connect-src 'self' https://plausible.io https://api.github.com;\"
    Cache-Control = \"public, max-age=0, must-revalidate\"

# Headers for static assets (long cache)
[[headers]]
  for = \"/assets/*\"
  [headers.values]
    Cache-Control = \"public, max-age=31536000, immutable\"

# Headers for HTML files (short cache, revalidate)
[[headers]]
  for = \"/*.html\"
  [headers.values]
    Cache-Control = \"public, max-age=300, must-revalidate\"

# Redirects (permanent and temporary)
[[redirects]]
  from = \"/old-posts/*\"
  to = \"/posts/:splat\"
  status = 301
  force = true

[[redirects]]
  from = \"/feed\"
  to = \"/index.xml\"
  status = 301

[[redirects]]
  from = \"/admin\"
  to = \"/admin/\"
  status = 301

# Netlify 2026 plugin configuration (image optimization, sitemap)
[[plugins]]
  package = \"@netlify/plugin-image-optimization\"
  [plugins.inputs]
    formats = [\"webp\", \"avif\"]
    quality = 85

[[plugins]]
  package = \"@netlify/plugin-sitemap\"
  [plugins.inputs]
    exclude = [\"/admin/*\", \"/api/*\"]

# Environment variables (set via Netlify dashboard, not here)
# HUGO_GITHUB_TOKEN = \"ghp_xxx\"  # For GitHub API integrations (e.g., star counts)
# PLAUSIBLE_SITE_ID = \"your-site-id\"  # For analytics

# Add to config.yaml markup section
markup:
  csp:
    enable: true
    mode: \"hash\"  # Hash inline scripts/styles instead of allowing 'unsafe-inline'
    reportOnly: false  # Set to true to test without enforcing

# Add to netlify.toml build.incremental section
[build.incremental]
  enable = true
  cache = [\"resources/_gen\", \"themes/PaperMod\", \"assets/css\"]

// netlify/edge-functions/comments.ts
import { Context } from \"https://edge.netlify.com/mod.ts\";

export default async (request: Request, context: Context) => {
  if (request.method !== \"POST\") return new Response(\"Method not allowed\", { status: 405 });
  const body = await request.json();
  // Validate input, post to GitHub Issues, return response
  return new Response(JSON.stringify({ \"success\": true }), { status: 200 });
};

tech-blog-hugo-netlify-2026/
├── assets/
│   ├── css/
│   │   └── custom.css  # Custom overrides for PaperMod theme
│   └── images/
│       └── profile.png  # Author profile image
├── content/
│   ├── posts/  # Blog posts (date-based)
│   │   ├── 2026-01-01-welcome-to-my-blog/
│   │   │   └── index.md
│   │   └── 2026-01-05-hugo-netlify-setup/
│   │       └── index.md
│   ├── guides/  # Long-form tutorials
│   │   └── 2026-01-10-step-by-step-hugo-guide/
│   │       └── index.md
│   ├── notes/  # Short engineering notes
│   │   └── 2026-01-15-go-interface-tips/
│   │       └── index.md
│   └── about/
│       └── index.md
├── layouts/
│   └── partials/  # Custom partials for comments, analytics
│       ├── comments.html
│       └── analytics.html
├── netlify/
│   └── edge-functions/
│       └── comments.ts  # Edge function for comment submission
├── static/
│   └── favicon.ico
├── themes/
│   └── PaperMod/  # Git submodule for theme
├── config.yaml  # Hugo configuration (code example 2)
├── netlify.toml  # Netlify configuration (code example 3)
├── setup-local-env.sh  # Local setup script (code example 1)
├── .gitmodules  # Git submodule config for theme
├── .gitignore  # Ignore generated resources, build dir
└── README.md  # Repo documentation