PKB-theme Demo

Hugo SEO Implementation Guide

Neural HD ~63 MB
One-time download · cached locally
Ready
1×
{{ site.Params.contact.profileName }}
Created:
documentation
SEO , Hugo , Search Optimization ...

This guide documents all SEO implementations, files, and configurations added to the PKB Hugo theme to ensure optimal search engine visibility and performance.

Theme Integration Architecture

Hugo Theme SEO Architecture
═══════════════════════════════════════════════════════════════════

                     ┌─────────────────┐
                     │   hugo.toml     │
                     │ (Site Config)   │
                     └─────────┬───────┘
                               │
                ┌──────────────┼──────────────┐
                │              │              │
        ┌───────▼──────┐  ┌────▼────┐  ┌─────▼─────┐
        │ data/seo.yml │  │ Content │  │ Static    │
        │ (SEO Config) │  │ Files   │  │ Assets    │
        └───────┬──────┘  └────┬────┘  └─────┬─────┘
                │              │              │
                └──────────────┼──────────────┘
                               │
                    ┌──────────▼──────────┐
                    │   LAYOUT SYSTEM     │
                    │ ─────────────────── │
                    │ baseof.html         │
                    │ ├─ <head>           │
                    │ │  ├─ head/meta     │
                    │ │  ├─ schema-org    │
                    │ │  └─ preload       │
                    │ └─ <body>           │
                    │    └─ content       │
                    └──────────┬──────────┘
                               │
                    ┌──────────▼──────────┐
                    │   GENERATED HTML    │
                    │ ─────────────────── │
                    │ • Meta Tags         │
                    │ • Schema Markup     │
                    │ • Preloaded Assets  │
                    │ • Optimized Images  │
                    │ • Robots.txt        │
                    │ • Sitemap.xml       │
                    └─────────────────────┘

Build Process:
Hugo native [sitemap] config ──► sitemap.xml
scripts/optimize-images.js  ──► WebP + responsive images
static/robots.txt ──► Crawler directives

SEO Files Created

Core Requirements (Always Needed)

  • /layouts/partials/head/meta.html - Meta tags
  • /layouts/partials/seo/schema-org.html - Structured data
  • /layouts/partials/seo/preload-resources.html - Performance
  • /static/robots.txt - Crawler directives
  • /config/_default/params.toml - SEO configuration

Optional Automation (Node.js Required)

  • /package.json - Only needed for advanced scripts
  • /scripts/optimize-images.js - Image optimization
  • /scripts/seo-audit.js - SEO validation

Basic vs Advanced Setup

Basic Setup (Hugo Only)

# No Node.js required
hugo --gc --minify

Features:

  • ✅ All meta tags and structured data
  • ✅ Hugo’s built-in sitemap generation
  • ✅ Hugo’s built-in image processing
  • ✅ Basic SEO optimization

Advanced Setup (Node.js + Hugo)

# Requires Node.js and npm install
npm run build:advanced

Additional Features:

  • 🚀 Advanced image optimization (WebP conversion)
  • 🚀 SEO validation and auditing
  • 🚀 Custom performance monitoring

Installation Options

# Clone the theme
git clone https://github.com/your-username/pkb-theme.git themes/pkb

# Build with Hugo's built-in features
hugo --gc --minify

# Clone the theme
git clone https://github.com/your-username/pkb-theme.git themes/pkb

# Install Node.js dependencies (optional)
npm install

# Build with advanced features
npm run build:advanced

When You Need package.json

Keep package.json if you want:

  • Advanced image optimization beyond Hugo’s capabilities
  • Custom SEO auditing and validation scripts
  • Automated performance monitoring
  • Integration with CI/CD pipelines

Skip package.json if you prefer:

  • Simpler Hugo-only workflow
  • No Node.js dependency management
  • Hugo’s built-in features are sufficient
  • Minimal setup complexity

SEO Files Created

Core SEO Templates

/layouts/partials/head/meta.html

Theme Integration: Main meta tags partial included in <head> section of baseof.html

How it works:

  • Consolidates all meta tag functionality in one file
  • Automatically generates meta tags for every page
  • Pulls data from frontmatter and site configuration
  • Creates fallback values when data is missing
  • Renders different meta tags based on page type (article, page, homepage)
  • Includes Open Graph, Twitter Cards, and SEO optimization

Template Usage:

<!-- In layouts/_default/baseof.html -->
<head>
  {{ partial "head/meta.html" . }}
</head>

Generated Output:

<meta name="description" content="Page description from frontmatter">
<meta property="og:title" content="Page Title">
<meta property="og:description" content="Page description">
<meta name="twitter:card" content="summary_large_image">
<link rel="canonical" href="https://yoursite.com/page-url/">

/layouts/partials/seo/schema-org.html

Theme Integration: Injected as JSON-LD in <head> section

How it works:

  • Generates structured data based on content type
  • Automatically detects article vs. page vs. homepage
  • Pulls author information from site parameters
  • Creates breadcrumb navigation structure
  • Validates schema format automatically

Template Logic:

{{ if .IsPage }}
  {{ /* Article Schema */ }}
{{ else if .IsHome }}
  {{ /* Organization Schema */ }}
{{ else }}
  {{ /* WebPage Schema */ }}
{{ end }}

Generated Schema Types:

  • Article for blog posts
  • Organization for site identity
  • BreadcrumbList for navigation
  • Person for author profiles

/layouts/partials/seo/preload-resources.html

Theme Integration: First partial in <head> for critical resource loading

How it works:

  • Preloads critical fonts before CSS parsing
  • Preloads hero images for above-the-fold content
  • DNS prefetching for external resources
  • Critical CSS inlining for faster rendering

Resource Priority:

  1. Critical fonts (highest priority)
  2. Hero images (high priority)
  3. CSS files (medium priority)
  4. External resources (low priority)

/static/robots.txt

Theme Integration: Static file served at /robots.txt URL

How it works:

  • Provides instructions to search engine crawlers
  • Controls which pages and directories to crawl or avoid
  • References sitemap location for better indexing
  • Blocks access to development and admin directories
  • Prevents crawling of duplicate content with parameters

Key Directives:

User-agent: *           # Apply to all crawlers
Allow: /               # Allow crawling of main content
Disallow: /admin/      # Block admin areas
Disallow: /drafts/     # Block draft content
Disallow: /*?utm_*     # Block tracking parameters
Sitemap: https://yoursite.com/sitemap.xml

Benefits:

  • Crawl Efficiency: Guides crawlers to important content
  • Server Resources: Reduces unnecessary requests
  • Duplicate Content: Prevents indexing of parameterized URLs
  • Privacy: Blocks private/admin sections
  • Sitemap Discovery: Helps search engines find your sitemap

Customization:

  • Update domain in sitemap URL
  • Add specific bot rules if needed
  • Adjust crawl delay for server capacity
  • Block aggressive crawlers if necessary

Configuration Files

/data/seo.yml

Theme Integration: Global SEO configuration accessible via site.Data.seo

How it works:

  • Centralizes all SEO settings in one file
  • Provides fallback values for missing frontmatter
  • Configures default keywords and meta information
  • Sets up organization schema data

Access Pattern:

{{ $seo := site.Data.seo }}
{{ $keywords := $seo.meta.keywords }}
{{ $org := $seo.schema.organization }}

Configuration Structure:

meta:
  keywords: ["Hugo", "Theme", "Blog", "Academic"]
  author: "Your Name"
  robots: "index, follow"
  default_image: "/images/default-og.jpg"
schema:
  organization:
    name: "PKB Theme"
    logo: "/images/logo.png"
    url: "https://yoursite.com"
    contactPoint:
      telephone: "+1-000-000-0000"
      contactType: "customer service"
social:
  twitter: "@yourhandle"
  facebook: "yourpage"
  linkedin: "yourprofile"

Updated hugo.toml

Theme Integration: Core Hugo configuration with SEO optimizations

SEO Enhancements Added:

# SEO Configuration
[params.seo]
  enable = true
  default_image = "images/default-og.jpg"
  twitter_creator = "@yourhandle"
  
# Image Processing
[imaging]
  quality = 85
  format = "webp"
  
# Sitemap Configuration
[sitemap]
  changefreq = "weekly"
  priority = 0.5
  filename = "sitemap.xml"
  
# RSS Configuration
[rss]
  limit = 20

Automation Files

Native sitemap (Hugo built-in)

The sitemap is generated by Hugo itself from the [sitemap] config table; no Node.js post-processing step is needed. (The legacy scripts/generate-sitemap.js helper was removed in 2026-07: it ran outside the build and overwrote Hugo’s own output.)

/scripts/optimize-images.js

Theme Integration: Processes images in /assets/images/ directory

How it works:

  • Converts images to WebP format with fallbacks
  • Generates responsive image variants
  • Optimizes file sizes without quality loss
  • Validates alt text presence
  • Updates image references in content

Processing Pipeline:

Original Image (JPG/PNG)
    ↓
WebP Conversion
    ↓
Responsive Variants (320w, 640w, 1024w, 1920w)
    ↓
Compression Optimization
    ↓
Output to /static/images/

Template Integration Flow

1. Page Rendering Process

Content File (.md)
    ↓
Hugo Processing
    ↓
Layout Selection (baseof.html)
    ↓
SEO Partials Execution
    ├─ head/meta.html
    ├─ schema-org.html
    └─ preload-resources.html
    ↓
Final HTML Output

2. Data Flow

Frontmatter → Hugo Variables → SEO Partials → HTML Output
     ↓              ↓              ↓
site.Data.seo → Template Logic → Meta Tags
     ↓              ↓              ↓
hugo.toml → Site Parameters → Schema Markup

3. Build Process

Hugo Build
    ├─ Content Processing
    ├─ SEO Partial Rendering
    ├─ Image Optimization (scripts/optimize-images.js)
    └─ Sitemap Generation (native Hugo [sitemap] output)
    ↓
Optimized Site Output

SEO Features Implemented

Crawler Management

  • Robots.txt: Controls search engine crawler behavior
  • Meta Robots: Page-level crawler directives
  • Sitemap Integration: Automatic sitemap discovery
  • Crawl Optimization: Efficient resource usage

Meta Tags & Structured Data

  • Open Graph: Complete Facebook/LinkedIn sharing optimization
  • Twitter Cards: Rich media cards for Twitter sharing
  • Schema.org: Structured data for search engines
  • Canonical URLs: Duplicate content prevention

Performance Optimization

  • Resource Preloading: Critical resources loaded first
  • Image Optimization: WebP format with fallbacks
  • Font Loading: Optimized web font delivery
  • CSS/JS Minification: Reduced file sizes

Content Optimization

  • Semantic HTML: Proper heading hierarchy
  • Alt Text: Image accessibility and SEO
  • Internal Linking: Related posts and navigation
  • Breadcrumbs: Clear site hierarchy

Usage Instructions

Basic Setup

  1. Update /data/seo.yml with your site information
  2. Configure hugo.toml with your domain and preferences
  3. Update /static/robots.txt with your domain
  4. Add appropriate images to /static/images/
  5. Ensure all posts have proper frontmatter

Robots.txt Configuration

  1. Update Sitemap URL: Replace https://yoursite.com/sitemap.xml with your actual domain
  2. Review Disallow Rules: Adjust blocked directories based on your site structure
  3. Test Crawler Access: Use Google Search Console to test robots.txt
  4. Monitor Crawl Behavior: Check for blocked important pages

Example Customization:

# Custom rules for your site
Disallow: /temp/
Disallow: /backup/
Allow: /api/public/
Sitemap: https://yourdomain.com/sitemap.xml

Frontmatter Requirements

title: "Your Post Title"
description: "Brief, compelling description (150-160 chars)"
date: 2024-12-19
image: "images/post-image.jpg"
tags: ["relevant", "tags"]
categories: ["Category"]

Image Optimization

  1. Place original images in /assets/images/
  2. Run npm run optimize-images to generate optimized versions
  3. Reference images using Hugo’s image processing functions

SEO Best Practices

Robots.txt Guidelines

  • Keep it Simple: Clear, concise directives
  • Test Regularly: Use Google Search Console robots.txt tester
  • Monitor Crawl Stats: Check for unintended blocking
  • Update Sitemap URL: Ensure it matches your actual domain
  • Be Specific: Use precise paths for disallow rules

Content Guidelines

  • Title Tags: 50-60 characters, include primary keyword
  • Meta Descriptions: 150-160 characters, compelling call-to-action
  • Headings: Use H1-H6 hierarchy properly
  • Internal Links: Link to related content using descriptive anchor text

Technical SEO

  • Page Speed: Aim for Core Web Vitals compliance
  • Mobile-First: Responsive design across all devices
  • HTTPS: Secure connection required
  • Clean URLs: Use Hugo’s slug configuration

Analytics Integration

<!-- Google Analytics 4 -->
<script async src="https://www.googletagmanager.com/gtag/js?id=GA_MEASUREMENT_ID"></script>
<!-- Search Console verification -->
<meta name="google-site-verification" content="verification_code">

Advanced Recommendations

Local SEO (if applicable)

  • Add local business schema
  • Include NAP (Name, Address, Phone) consistency
  • Create location-specific pages

International SEO

  • Implement hreflang tags for multi-language sites
  • Use proper URL structure (/en/, /es/, etc.)
  • Localize meta tags and structured data

E-A-T Optimization

  • Expertise: Demonstrate subject matter knowledge
  • Authoritativeness: Build quality backlinks
  • Trustworthiness: Include author bios, contact information

Monitoring & Maintenance

  1. Google Search Console: Monitor indexing and performance
  2. Page Speed Insights: Regular performance audits
  3. Structured Data Testing: Validate schema implementation
  4. SEO Audits: Quarterly comprehensive reviews

Troubleshooting

Common Issues

  • Missing Images: Check image paths and optimization scripts
  • Schema Errors: Validate using Google’s Structured Data Testing Tool
  • Slow Loading: Review preload configurations and image sizes
  • Indexing Issues: Check robots.txt and sitemap accessibility
  • Robots.txt Not Found: Ensure file is in /static/ directory
  • Incorrect Sitemap URL: Update domain in robots.txt
  • Blocking Important Pages: Review disallow rules carefully
  • Crawler Errors: Monitor Search Console for blocked resources

Robots.txt Testing

  1. Google Search Console: Use robots.txt tester tool
  2. Direct Access: Visit yoursite.com/robots.txt to verify
  3. Crawl Simulation: Test with various user agents
  4. Sitemap Validation: Ensure sitemap URL is accessible

Validation Tools

Important Notes

File Consolidation

  • Previous: /layouts/partials/seo/meta-tags.html (removed)
  • Current: /layouts/partials/head/meta.html (consolidated)
  • Benefit: Single source of truth for all meta tags with enhanced SEO features

Migration Required

If you have existing layout files referencing the old partial:

Old Reference (remove):

{{ partial "seo/meta-tags.html" . }}

New Reference (use):

{{ partial "head/meta.html" . }}

This SEO implementation provides a solid foundation for search engine optimization. The robots.txt file ensures efficient crawling while protecting sensitive areas of your site. Regular monitoring and updates ensure continued effectiveness as search algorithms evolve.

Related notes: Creating Posts with Hugo, Development Tips, SOTA: Hugo. See also the glossary for shared terminology.