Hugo Blog SEO: A Complete Guide from Principles to Practice

It doesn’t matter how good your content is — if search engines can’t crawl it and users can’t find it, it might as well not exist. That sounds harsh, but for the vast majority of independent blogs it’s simply the truth. Your server sits on some VPS, your domain has little authority, backlinks are scarce, and Googlebot might swing by only once a month — and every time it does, it sees the same content from weeks ago. The keywords readers type into the search box will never point to your pages. A painstakingly polished technical article ends up gathering dust in your own archive page.

The essence of SEO (Search Engine Optimization) is not the black-hat tricks of keyword stuffing and link farming. It comes down to three plain demands: make search engines correctly understand your content, correctly present your page, and correctly bring users to you. “Understand” means crawlers can fetch it and the index can parse it; “present” means the title, snippet, and rich media card in the search results look the way you want; “bring users” means ranking high enough and a click-through rate high enough. Break these three apart, and each one maps to a concrete set of engineering actions.

This article doesn’t deal in mysticism — only the engineering practice of technical SEO, with a Hugo static blog as the vehicle. Static sites have a natural advantage: no database queries, no server-side rendering latency, stable URLs. But that advantage doesn’t automatically turn into rankings — every item has to be configured correctly. The final section uses my own blog as a case study, landing every optimization in a real project, including the pitfalls I hit and a rather sneaky Hugo sorting bug.

What SEO Is: The Three Stages of How Search Engines Work

To do SEO well, you first have to understand how search engines work. None of the SEO techniques are rules invented out of thin air — they are all accommodations to the underlying mechanics of search engines. The core pipeline of a search engine breaks down into three stages: Crawl → Index → Rank.

flowchart TD
    A["Crawler"] --> B["URL Frontier<br/>Fetch Queue"]
    B --> C["Download Page HTML"]
    C --> D["Parse Content<br/>Extract Links"]
    D --> E["Index Store"]
    E --> F["User Query"]
    F --> G["Relevance + Authority<br/>Ranking"]
    G --> H["Search Results Display"]

    style A fill:#e3f2fd,stroke:#2196f3,stroke-width:2px
    style E fill:#e8f5e9,stroke:#4caf50,stroke-width:2px
    style G fill:#fff3e0,stroke:#ff9800,stroke-width:2px
    style H fill:#f3e5f5,stroke:#9c27b0,stroke-width:2px

The diagram above shows the complete path a search engine takes from discovering a URL to finally displaying results. A crawler (such as Googlebot) starts from a known set of seed URLs, places the links to be fetched into the URL Frontier queue, and downloads the HTML one by one by priority. After downloading, it parses the content, extracts new links from the page (this is how a crawler keeps spreading), and stores the parsed text, titles, and link relationships in the index store. When a user searches, the system ranks pages from the index store by the query’s relevance and the page’s overall authority, then displays them on the results page. The three stages are tightly chained — break any one link, and your page drops out of the chain.

Once you understand the three stages, you understand why SEO is broken into so many items — each technique corresponds to one of these stages:

This comparison table is the outline for the entire article. Each following section is an engineering optimization at one of these stages.

Core Elements of Technical SEO

URL Structure and Canonical

SEO-friendly URLs have five traits: short, semantic (containing keywords), free of query parameters, all lowercase, and stable. A good URL looks like this:

1

https://example.com/posts/iot/esp32-cam-flash/

Both readers and crawlers can tell at a glance that this is about flashing an ESP32-CAM. A bad URL looks like this:

1

https://example.com/p?id=1234&cat=7&sid=abc

Parameterized, non-semantic, and unstable (change the id and the URL changes) — crawlers struggle to tell whether this is a new page.

In Hugo, the URL is determined by the content file path. Place an article at content/posts/iot/esp32-cam-flash.md and the default generated URL is /posts/iot/esp32-cam-flash/ — inherently semantic and parameter-free. This is a major SEO advantage of static sites over dynamic ones. If you need finer control, you can override it with the url field in front matter, or adjust permalinks in the site config:

1
2

permalinks:
  posts: /posts/:sections/:slugorfilename/

Even more critical is the canonical tag. Its job is to tell search engines “which URL is the authoritative one for this page,” preventing duplicate content from being misjudged. Duplicate content is actually very common in Hugo — the same article may be reachable through /posts/foo/, /posts/foo/index.html, /zh/posts/foo/, list pages with pagination parameters, and more. Without canonical, search engines treat them as multiple independent pages, each diluting authority, and may even trigger a “duplicate content demotion.”

The correct approach is to emit canonical in the <head> of every page:

1

<link rel="canonical" href="{{ .Permalink }}" />

.Permalink is the absolute authoritative URL that Hugo computes from the current page and baseURL.

Here there’s a very common and fatal mistake: configuring baseURL as a relative path /. In Hugo’s config, baseURL must be a complete absolute domain:

1
2
3
4
5

# ❌ Wrong: relative path
baseURL: /

# ✅ Correct: absolute URL, with protocol and domain
baseURL: https://mickeyzzc.github.io/

When set to a relative path, .Permalink resolves to something like localhost/posts/foo/, and canonical, sitemap, and Open Graph all go wrong with it — you’re literally telling search engines “the authoritative address for this page is localhost.” The consequence: the live page’s canonical points to an address that can’t even be opened, so Google either ignores your canonical or simply doesn’t index the page.

Another sneaky pitfall is pagination pages whose canonical duplicates point to the homepage. If page 2 and page 3 of a list page all have their canonical pointing back to page 1, Google considers them copies of the homepage and keeps only the homepage — so articles beyond page 2 lose their index entry on the category page. The correct approach is for pagination pages to canonicalize to themselves:

1
2
3
4

{{ range $i, $e := .Paginator.Pages }}
  <!-- list items -->
{{ end }}
<link rel="canonical" href="{{ .Paginator.URL | absURL }}" />

Title and Meta Description

The title is the single most important point in all of SEO, bar none. The weight search engines assign to the title is far higher than any other single signal. Writing a good title comes down to two things:

1. Length of 50-60 characters. Anything beyond that gets truncated to ... in the search results, and keywords in the latter part simply aren’t visible.
2. Core keywords up front. “Hugo Blog SEO Complete Guide” is better than “Complete Guide: How to Do Blog SEO with Hugo,” because the keywords come in the first half.

In Hugo templates, the title is usually organized like this:

1

<title>{{ .Title }}{{ with .Site.Params.titleSuffix }} - {{ . }}{{ end }}</title>

Article pages use .Title; the homepage and category pages use the site name plus the site description. Be careful not to share one title template across all pages (e.g., all called “My Blog”) — that’s the same as having no title at all.

meta description doesn’t directly affect ranking, but it heavily affects click-through rate (CTR). Google uses it as the snippet text beneath the search result card. A good description is a 150-160 character piece of “ad copy” — it explains what the content is about and what the reader will get, and draws the click.

1
2
3

{{ with .Description }}
  <meta name="description" content="{{ . }}" />
{{ end }}

.Description reads the description field from front matter.

Here’s a fatal mistake that’s all too easy to overlook: a large number of articles have no description field written. Templates usually include a fallback:

1
2

{{ $desc := .Description | default .Site.Params.description }}
<meta name="description" content="{{ $desc }}" />

This means every article without a description shares a site-level fallback description (something like “Mickey’s personal tech blog, recording practices in programming, IoT, and observability”). The consequences are disastrous:

• Google ignores this cookie-cutter description and grabs the body text itself for the snippet. You lose all control over the snippet, and what gets pulled may be nonsense like “see references at the end” from the article’s opening.
• The search result cards look identical, so readers can’t tell which article is which, and CTR collapses.

The correct approach is to write a description for every article, and they should differ from one another. List pages and category pages also need their own descriptions — e.g., “All articles under the observability category, covering Prometheus, VictoriaMetrics, eBPF” — rather than continuing to fall back to the site description.

Structured Data: JSON-LD

Structured data uses the schema.org vocabulary to tag page content with “machine-readable labels.” Plain HTML tells a browser “this is a heading, this is a paragraph”; structured data tells a search engine “this is an article, the author is so-and-so, the publish date is such-and-such.”

Why does it matter? Because it can trigger Google’s rich results. A normal search result is one line of blue title plus two lines of gray snippet; a rich result is a card with a cover image, star ratings, breadcrumb navigation, a collapsible FAQ — taking up more screen space, more visually prominent, and with a significantly higher CTR. On mobile, an Article card can fill most of the screen.

The structured data format Google recommends is JSON-LD (JavaScript Object Notation for Linked Data). Compared to the other two formats — Microdata (adding itemprop inside HTML tags) and RDFa — JSON-LD keeps the data isolated inside a single <script> tag, doesn’t pollute the HTML structure, and is far easier to maintain and validate:

1
2
3

<script type="application/ld+json">
{ ... }
</script>

There are four key schema types:

• BlogPosting / Article: article content, triggers article cards
• WebSite: site-level, can include SearchAction (lets Google show a site search box)
• BreadcrumbList: breadcrumbs, triggers breadcrumb navigation in results
• Organization / Person: site publisher information

The essentials of implementing JSON-LD in Hugo are using dict to build the data, jsonify to serialize, and safeJS to mark it as safe JS. Here’s an encoding bug that’s easy to hit:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{{- $schema := dict
    "@context" "https://schema.org"
    "@type" "BlogPosting"
    "headline" .Title
    "datePublished" .Date
    "author" (dict "@type" "Person" "name" .Site.Params.author)
    "image" (.Params.cover | default .Site.Params.defaultOGImage | absURL)
    "mainEntityOfPage" (dict "@type" "WebPage" "@id" .Permalink)
-}}
<script type="application/ld+json">
{{ $schema | jsonify | safeJS }}
</script>

Note the safeJS at the end. Without it, Hugo treats the JSON string as plain text and HTML-escapes it — turning & into & and < into <. When the browser parses the JS, the escaped characters inside the JSON string become double-encoded (for example, & in a URL becomes &, which JSON then parses as the string literal & instead of &), so all the links and special characters in the structured data end up wrong. With safeJS, Hugo outputs it as-is, and the JSON can be correctly parsed by search engines.

A complete BlogPosting JSON-LD example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

{{- $authors := slice -}}
{{- with .Params.authors -}}
  {{- range . }}{{ $authors = $authors | append (dict "@type" "Person" "name" .) }}{{ end -}}
{{- else -}}
  {{- $authors = $authors | append (dict "@type" "Person" "name" .Site.Params.author) -}}
{{- end -}}
{{- $schema := dict
    "@context" "https://schema.org"
    "@type" "BlogPosting"
    "mainEntityOfPage" (dict "@type" "WebPage" "@id" .Permalink)
    "headline" (.Title | plainify)
    "description" (.Description | default (plainify .Summary))
    "image" (slice (dict "@type" "ImageObject" "url" ((.Params.cover | default .Site.Params.defaultOGImage) | absURL)))
    "datePublished" (.Date.Format "2006-01-02T15:04:05Z07:00")
    "dateModified" ((.Lastmod | default .Date).Format "2006-01-02T15:04:05Z07:00")
    "author" $authors
    "publisher" (dict
        "@type" "Organization"
        "name" .Site.Params.author
        "logo" (dict "@type" "ImageObject" "url" (.Site.Params.logo | absURL))
    )
-}}
<script type="application/ld+json">
{{ $schema | jsonify | safeJS }}
</script>

Once written, always validate it with Google’s Rich Results Test to ensure there are no syntax errors and no missing required fields.

Open Graph and Social Sharing

The Open Graph (og:) protocol originated at Facebook and is now a de facto standard — Facebook, WeChat, Twitter/X, Telegram, DingTalk, and virtually every social platform, when crawling a link you share, uses the og: tags to generate that preview card (title + description + large image). If JSON-LD serves search engines, Open Graph serves social sharing.

Core properties:

1
2
3
4
5
6

<meta property="og:title" content="Article Title" />
<meta property="og:description" content="Article summary" />
<meta property="og:image" content="https://example.com/cover.jpg" />
<meta property="og:url" content="https://example.com/posts/foo/" />
<meta property="og:type" content="article" />
<meta property="og:site_name" content="Site Name" />

Hugo template implementation:

1
2
3
4
5
6

<meta property="og:title" content="{{ .Title }}" />
<meta property="og:description" content="{{ with .Description }}{{ . }}{{ else }}{{ .Site.Params.description }}{{ end }}" />
<meta property="og:type" content="{{ if .IsPage }}article{{ else }}website{{ end }}" />
<meta property="og:url" content="{{ .Permalink }}" />
<meta property="og:site_name" content="{{ .Site.Title }}" />
<meta property="og:image" content="{{ (.Params.cover | default .Site.Params.defaultOGImage) | absURL }}" />

The most critical rule: og:image and og:url must be absolute URLs. Social platform crawlers won’t resolve relative paths for you — handed a relative path like images/cover.jpg, it has no idea which domain it’s relative to, and the result is that the card’s image is always broken. The absURL function turns a relative path into a complete URL based on baseURL.

og:image should also meet 1200×630 pixels — the universal ratio for preview cards across major social platforms. Anything smaller gets cropped or blurred; anything larger only adds load time.

Twitter/X uses its own set of Twitter Card tags, but the core fields overlap with Open Graph:

1
2
3
4

<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:title" content="..." />
<meta name="twitter:description" content="..." />
<meta name="twitter:image" content="..." />

Set twitter:card to summary_large_image to get the large-image card. If you omit fields like twitter:title, Twitter automatically falls back to the corresponding og: tags, so you can write a single set of og: tags and just add a twitter:card.

Multilingual SEO: hreflang

If a site has multiple language versions, the hreflang tag tells search engines “this page has other language versions, and here are their URLs.” Its job isn’t to directly affect ranking, but to let Google show users in different regions the corresponding language version in the search results — Chinese users see the Chinese version, American users see the English version.

Format:

1
2

<link rel="alternate" hreflang="zh-CN" href="https://example.com/zh/posts/foo/" />
<link rel="alternate" hreflang="en" href="https://example.com/en/posts/foo/" />

You must pair it with an x-default that points to the default language version:

1

<link rel="alternate" hreflang="x-default" href="https://example.com/posts/foo/" />

Omitting x-default is a common mistake. Google’s documentation explicitly requires it: when a user’s language doesn’t match any declared version, fall back to x-default. Skipping it leaves some search traffic without a suitable landing page.

The Hugo implementation for a multilingual site iterates over .AllTranslations (which includes the current language):

1
2
3
4
5
6

{{- if .IsTranslated -}}
  {{- range .AllTranslations -}}
    <link rel="alternate" hreflang="{{ .Language.LanguageCode }}" href="{{ .Permalink }}" />
  {{- end -}}
  <link rel="alternate" hreflang="x-default" href="{{ .Site.Home.Permalink }}" />
{{- end -}}

Language code conventions: use zh-CN (not zh-cn — it’s case-sensitive; Google requires the BCP 47 standard with an uppercase region code), en or en-US, ja, ko. When setting languageCode in Hugo’s site config, mind the casing:

1
2
3
4
5
6
7

languages:
  zh-cn:
    languageCode: zh-CN
    weight: 1
  en:
    languageCode: en
    weight: 2

Sitemap and robots.txt

sitemap.xml is a site map that tells search engines “here are my pages and when they were last updated.” It solves a discovery problem — especially for new sites and sites with few backlinks, where a crawler might go a long time without naturally finding some of your deep pages. A sitemap proactively feeds all your URLs to it.

Hugo generates public/sitemap.xml automatically by default, with no configuration needed. Multilingual sites generate a sitemap index pointing to per-language sub-sitemaps. You can customize it via a layouts/sitemap.xml template — for example, adding lastmod and priority to each URL:

1
2
3
4
5
6
7
8
9

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  {{ range .Data.Pages }}
  <url>
    <loc>{{ .Permalink }}</loc>
    <lastmod>{{ .Lastmod.Format "2006-01-02T15:04:05Z07:00" }}</lastmod>
  </url>
  {{ end }}
</urlset>

robots.txt does the reverse — it tells crawlers “what you may and may not crawl.” It can also declare the location of the sitemap. But here’s the catch: Hugo’s default generated robots.txt is virtual (not written to disk) and doesn’t include a Sitemap directive. To get it to output a real robots.txt that declares the sitemap, you need to:

1. Enable the custom template in the site config:

1
2

siteConfig:
  enableRobotsTXT: true

2. Create layouts/robots.txt:

1
2
3
4
5
6

User-agent: *
{{- range .Site.Params.robotsDisallow -}}
Disallow: {{ . }}
{{- end }}

Sitemap: {{ "sitemap.xml" | absURL }}

The Sitemap: line is critical. Visiting /robots.txt is one of a crawler’s routine actions — seeing the Sitemap directive prompts it to actively fetch the sitemap, which is less hassle than manually submitting it in GSC. Without that line, search engines can only discover pages by “crawling along the homepage’s links,” and indexing deep pages becomes very slow.

Typical paths to disallow include /tags/, /categories/ (aggregation pages with high content duplication), /admin/, /api/, and so on:

1
2
3
4

params:
  robotsDisallow:
    - /tags/
    - /categories/

Performance: Core Web Vitals

Starting in 2021, Google officially made Core Web Vitals a ranking factor. No matter how good your content is or how complete your structured data is, if the page loads slowly and interactions feel janky, your ranking gets penalized. The three core metrics:

• LCP (Largest Contentful Paint): the time it takes for the main content of the page to finish rendering, target <2.5 seconds. The largest element is usually the hero image or the title block.
• INP (Interaction to Next Paint): the time from a user’s first interaction to the next frame rendered, target <200 milliseconds. INP replaced the old FID in 2024.
• CLS (Cumulative Layout Shift): how much element positions jump around during page load, target <0.1. The classic symptoms of high CLS: an image finishes loading and shoves the text below it down, or a font loads and the text position jumps.

A Hugo static site is inherently performant — no database, no server-side rendering, all files pre-generated — but there are still a few things you must do proactively:

Run JS/CSS through Hugo Pipes. Use Hugo’s asset pipeline for minify, fingerprint, and concat, plus defer for async loading:

1
2
3
4
5

{{- $js := resources.Get "js/main.js" | js.Build (dict "minify" true) | fingerprint -}}
<script src="{{ $js.RelPermalink }}" defer></script>

{{- $css := resources.Get "scss/main.scss" | toCSS | minify | fingerprint -}}
<link rel="stylesheet" href="{{ $css.RelPermalink }}" />

fingerprint makes the filename carry a hash (e.g., main.a3b2c1.js), so you can confidently set a very long cache time (Cache-Control: max-age=31536000, immutable) — when the file changes, the hash changes, and the browser re-fetches automatically. This is the killer performance config for static sites.

Lazy-load images and reserve their dimensions. Add loading="lazy" to all non-above-the-fold images; at the same time, you must give the <img> explicit width and height so the browser reserves the canvas before the image downloads — this is the key to eliminating CLS:

1

<img src="cover.jpg" width="1200" height="630" loading="lazy" decoding="async" alt="..." />

Load third-party scripts on demand. The classic counterexample is Mermaid — it’s a JS library of several hundred KB, and if every page loads it via CDN, even articles without diagrams pay that volume for nothing. The right approach is to include it only on pages with mermaid: true:

1
2
3
4

{{- if .Params.mermaid -}}
  {{- $mermaid := resources.GetRemote "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.min.js" -}}
  <script src="{{ $mermaid.RelPermalink }}" defer></script>
{{- end -}}

And add defer so it doesn’t block first-screen rendering.

Prefer a system font stack for fonts. Web fonts (Google Fonts, self-hosted woff2) look nice, but every weight is an extra request, and during loading the text either flashes (FOUT) or is invisible (FOIT) — both slowing LCP and creating CLS. For a tech blog, a system font stack (-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "PingFang SC", "Microsoft YaHei", sans-serif) is nearly zero-cost and gives a better native experience on each platform.

How to Measure SEO Results

SEO isn’t “do it once and it works” — it requires long-term observation and continuous adjustment. Finishing the optimizations isn’t the end; you have to look at the data to verify the results. This is a step many people skip — without data, you can’t tell which optimizations worked and which were wasted effort.

Google Search Console

Google Search Console (GSC) is the single authoritative data source for measuring SEO results. It comes straight from Google itself, unlike third-party tools that estimate. The core data GSC provides:

• Query: what terms users searched when they saw your page
• Impressions: how many times your page was shown in search results
• Clicks: how many times users actually clicked
• Average Position: your average ranking for that query
• CTR (click-through rate): clicks / impressions, reflecting how attractive your title and description are
• Index Coverage: which pages got indexed, which were excluded, and why
• Core Web Vitals: performance data from real user visits

Onboarding steps:

1. Add your site: enter the domain (the Domain property is recommended, covering all subdomains and protocols) or a URL prefix
2. Verify ownership: the most robust is a DNS TXT record (add a TXT record in your DNS settings, done once and for all, covering all subdomains); alternatives are a meta tag (add a line <meta name="google-site-verification" content="..." /> to the <head> of every page) or an HTML file upload
3. Submit your sitemap: in GSC’s “Sitemaps,” submit https://example.com/sitemap.xml

Key timing expectations: GSC data has a 2-3 day delay — what you see today is search data from 2-3 days ago. A new site typically takes 1-2 weeks from submission to first indexing, and ranking goes from first appearance to stable in 4-8 weeks — so don’t check the data the day after an optimization; that only breeds anxiety. Treat optimization as a quarterly effort to observe.

Bing Webmaster Tools

Bing Webmaster Tools is Bing’s equivalent. Its importance lies in the fact that Bing also powers search results for DuckDuckGo, Yahoo, Ecosia, and others, so optimizations on Bing radiate out to these search engines, covering a fair amount of Western traffic.

The onboarding flow is the same as GSC: add site → verify (meta or DNS) → submit sitemap. Bing can also import sites directly from GSC, saving you the repeat verification.

One highlight of Bing is its support for the IndexNow protocol — after publishing a new article or updating an old one, you actively ping Bing’s IndexNow endpoint, and Bingbot comes to crawl immediately, compressing indexing time from days down to hours. With Hugo, this is achievable via a simple deployment script:

1
2
3
4
5
6
7
8

# Call IndexNow after deployment
curl -X POST "https://api.indexnow.org/indexnow" \
  -H "Content-Type: application/json" \
  -d '{
    "host": "example.com",
    "key": "your-key",
    "urlList": ["https://example.com/posts/new-post/"]
  }'

Traffic Analytics Platforms

GSC only tells you the “search side” of the story — what terms, what ranking, how many clicks. But what do users do after they click through? How many pages do they view? How long do they stay? GSC doesn’t provide this; you need a session-level analytics platform to fill in the “traffic side” data.

Traditional Google Analytics is powerful but heavy, uses cookies, and is a pain for privacy compliance. For a personal blog, two lightweight, self-hosted, cookie-free, privacy-friendly options are recommended:

• Umami: open source, self-hosted, clean interface, supports multiple sites
• Plausible: open source (but mainly SaaS), zero cookies, no GDPR banner needed

Together with GSC, these form a closed loop: query (GSC) → ranking (GSC) → click (GSC) → landing (analytics) → behavior (analytics). For example, if you find an article has high impressions but a low CTR in GSC, it means the title/description isn’t attractive enough and you can go rewrite it; or if clicks are high but the analytics platform shows a high bounce rate, it means the content didn’t satisfy the search intent and you need to add content.

A Hugo Blog SEO Optimization in Practice

With the principles covered, let’s return to engineering reality. This section uses my own blog (this very blog) as a case study, running every piece of theory above through a real project. Every problem is a real pitfall I hit.

Problems Found

I ran a complete SEO audit on this Hugo blog, and the problems it turned up were alarming:

• baseURL was a relative path /, causing canonical, sitemap, and Open Graph to all point to localhost — the live page’s authoritative URL was an address that couldn’t even be opened
• About 30% of articles had no description field, all sharing one site-level fallback description, so Google’s snippets were cookie-cutter
• No structured data at all (JSON-LD) — search results were all plain text, no article cards, no breadcrumbs
• og:image was a relative path, so social platform crawlers couldn’t fetch the image, and share cards were always broken
• hreflang was missing x-default, leaving some language traffic without a suitable landing page
• Pagination pages had their canonical duplicated to the homepage, so articles beyond page 2 lost their index entry on the category page
• robots.txt had no Sitemap directive, so crawlers could only crawl along links, and deep pages indexed slowly
• Mermaid JS was loaded from CDN on every page, so even articles without diagrams paid that volume, slowing LCP

Optimization Measures

Each problem was fixed one by one:

None of these measures is complicated in isolation, but stacked together the effect is significant. Before the audit, it took Google nearly 3 weeks to index this site, and only the homepage and a handful of articles made it into the index; after the audit and fixes, new articles consistently go from publish to indexed in 3-5 days, and the search results presentation is much richer.

A Sneaky Hugo Sorting Bug (Real Case)

During the audit I also hit a rather sneaky pitfall — indirectly related to SEO but well worth recording: articles weren’t sorted by date.

Symptom: The homepage article order was jumbled, and the most recently published article wasn’t at the top — it was stuck somewhere in the middle. From a reader’s perspective, the “latest articles entry” was broken and the bounce rate rose; from an SEO perspective, the internal-link authority flow from the homepage’s newest content was also scrambled.

Root cause: The theme template’s head.html called a bare .Paginator:

1
2
3
4
5

{{- /* inside head.html */ -}}
{{- $paginator := .Paginator -}}
{{- range $paginator.Pages -}}
  ...
{{- end -}}

While the actual list rendering in home.html explicitly sorted by date:

1
2
3
4
5
6

{{- /* inside home.html */ -}}
{{- $sorted := sort .Pages "Date" "desc" -}}
{{- $paginator := .Paginate $sorted -}}
{{- range $paginator.Pages -}}
  ...
{{- end -}}

The problem is that Hugo’s .Paginate has a “first-call locks” mechanism. The first time .Paginator or .Paginate is called, Hugo locks the page sequence used for pagination; all subsequent calls reuse that locked sequence, no matter what arguments you pass afterward.

Because head.html (which executes first when baseof.html renders) called the bare .Paginator first, Hugo locked the pagination sequence using the default weight-first sort — and most of our articles have a weight field (used for ordering within a series). As a result, the homepage sorted by weight, with old articles that had small weight floating to the top, and the newest ones (large weight or no weight) sinking to the bottom. The sort by date in home.html was completely ignored.

The fix: In the earliest-executing template (baseof.html), initialize the Paginator once with an explicitly sorted sequence:

1
2
3

{{- /* very top of baseof.html */ -}}
{{- $pages := sort .Pages "Date" "desc" -}}
{{- $paginator := .Paginate $pages -}}

After that, every .Paginator across all templates (head, home, list) reuses this “descending by date” locked sequence.

Lesson learned: Hugo’s pagination-locking mechanism is implicit and silent — your sort fails silently, with no compile warning. Once you call pagination in multiple templates, you must initialize it once with an explicit sort in the earliest-executing template, and only that once. This one took a long time to track down, because on the surface “nothing was broken” — only the sorting was off, which is easy to mistake for a data problem.

References

• Google Search Central Documentation — Google’s official authoritative SEO guide, covering all the specs for crawling, indexing, and ranking
• schema.org — the official structured data vocabulary specification, the source of all JSON-LD types and properties
• Open Graph Protocol (ogp.me) — the official Open Graph protocol specification
• Hugo Official Documentation - SEO — Hugo template’s SEO-related section (sitemap, robots, RSS)
• web.dev - Core Web Vitals — Google’s official definitions and measurement methods for LCP/INP/CLS
• Bing Webmaster Guidelines — Bing’s webmaster guidelines and IndexNow protocol documentation