Skip to content

Analytics and SEO

Configure an optional analytics service. Check the canonical URLs, hreflang links, social cards, sitemap, and robots output that the theme generates.

By default, the theme loads no analytics, form, or advertising script. It makes no outbound request until you configure one. You must explicitly configure each integration. Document this external data boundary in the site’s privacy statement.

The theme automatically generates canonical links, hreflang links, the robots meta tag, Open Graph cards, and Twitter cards for each page. Set baseURL and each page’s description correctly.

Connecting Google Analytics

Use Hugo’s built-in service configuration. Replace G-YOUR_MEASUREMENT_ID with your own GA4 measurement ID before enabling this block:

hugo.yml
services:
  googleAnalytics:
    id: G-YOUR_MEASUREMENT_ID

The theme renders this script only in the production environment. A normal hugo server uses development and sends no analytics reports. A hugo build defaults to production, including on a preview host. For PR and staging deployments, select a non-production environment. Set PREVIEW_URL to the deployment’s actual address:

Terminal
hugo --environment staging --baseURL "$PREVIEW_URL"

See preview deployment settings.

Do not also set the deprecated top-level googleAnalytics key. If you do not want analytics, delete the block. Do not enter a fake ID.

This is incompatible with a network-isolated environment

When you configure this integration, it sends page views and events to Google. A strict same-origin Content Security Policy must also permit it. See Content Security Policy. The site must choose to enable this integration. The theme does not enable it by default.

Connecting another analytics service

To connect Plausible, Umami, Matomo, or a similar service, insert its script. The theme provides two injection points. Create a file with the corresponding name in the site repository. You do not need to change the theme:

layouts/_partials/hooks/head-end.html , Insertion pointBefore </head>, ahead of the Google Analytics template
Analytics scripts, cookie consent scripts, meta tags the theme does not provide
layouts/_partials/hooks/body-end.html , Insertion pointLast among the page scripts
Third-party code that affects interaction instead of the first paint

For Plausible, replace your-site.example with the domain registered in your own account before adding this hook:

layouts/_partials/hooks/head-end.html
{{ if hugo.IsProduction }}
<script defer data-domain="your-site.example"
        src="https://plausible.io/js/script.js"></script>
{{ end }}

Do not omit the hugo.IsProduction guard. Without it, each local preview sends reports to your analytics service.

head-end runs before Google Analytics

A cookie consent script must run before the analytics script. This order lets the consent script prevent analytics from running.

The “was this page helpful?” feedback widget is separate. It is off by default and makes no network request. Configure it as described in Repository links and page info.

Duo view panes

With params.ui.compare enabled, opening the duo view loads both pages inside same-origin frames. Theme-managed analytics (services.googleAnalytics.id and params.analytics.*) skips those panes automatically so opening the reader does not double-count page views. When params.ui.compare: true is active, OINK renders the Google Analytics snippet through its own pane-aware template rather than Hugo’s built-in partial, so a site override at layouts/_partials/google_analytics.html will not take effect.

Custom scripts in head-end.html still execute on every frame load. Guard them with window.OinkComparePane before recording a page view:

layouts/_partials/hooks/head-end.html
{{ if hugo.IsProduction }}
<script>
  if (!window.OinkComparePane) {
    var script = document.createElement('script');
    script.defer = true;
    script.dataset.domain = 'your-site.example';
    script.src = 'https://plausible.io/js/script.js';
    document.head.appendChild(script);
  }
</script>
{{ end }}

Server and CDN analytics also see pane requests. They carry the query oink_compare_pane=1 and can be filtered out.

Page descriptions

<meta name="description"> takes the first non-empty value of:

  1. The page’s description front matter
  2. The page summary Hugo computes (.Summary)
  3. params.description in the site configuration

Authors need only write one description per page for SEO. It supplies the search engine snippet, the card subtitle on a section index, and the result preview in site search.

content/docs/admin/analytics.md (this page)
---
title: Analytics and SEO
description: Connect an analytics service (or none), and pair up the canonical, hreflang, social cards, sitemap and robots the theme already generates.
---

For a multilingual site, write one description per language. Do not copy the English description to a Chinese page. Set the site-level default per language too:

hugo.yml
languages:
  en:
    params:
      description: A Hugo theme for engineering docs
  zh:
    params:
      description: 为工程而设计的 Hugo 文档主题

canonical and hreflang

The theme emits one canonical link per page and hreflang alternate links for actual translations. No configuration is required:

rendered output (this page)
<link rel="canonical" href="https://oink.pgsty.com/docs/admin/analytics/">
<link rel="alternate" hreflang="en-US" href="https://oink.pgsty.com/docs/admin/analytics/">
<link rel="alternate" hreflang="zh-CN" href="https://oink.pgsty.com/zh/docs/admin/analytics/">

The hreflang codes use each language’s locale (en-US / zh-CN on this site) and follow Hugo’s translation graph. Since OINK 1.2.0, untranslated pages omit hreflang and og:locale:alternate tags even when the visible language switcher links back to the target language’s home page.

Each paginated Blog index page uses its own canonical URL, and pages 2 and above omit hreflang alternate links because pagination boundaries can differ between languages. (OINK 1.1.0 retained the earlier behavior.)

The canonical URL uses baseURL. An incorrect baseURL directs search engines to addresses that do not exist. This problem is less visible than a build failure. Complete the deployment checklist before launch.

Full multilingual configuration is in Languages.

Social cards

The theme calls Hugo’s built-in Open Graph and Twitter card templates. They automatically supply the title, description, URL, language, and site name:

rendered output (this page)
<meta property="og:title" content="Analytics and SEO">
<meta property="og:type" content="article">
<meta property="og:url" content="https://oink.pgsty.com/docs/admin/analytics/">
<meta property="og:locale" content="en_US">
<meta property="og:locale:alternate" content="zh_CN">
<meta name="twitter:card" content="summary">

To give a shared link an image, set images in front matter:

any page
---
title: OINK v0.8.0 released
images: [/images/releasenote.webp]
---

For a site-wide fallback, write the same key under params:

hugo.yml
params:
  images: [/images/oink.webp]

When an image is present, twitter:card changes from summary to summary_large_image. The output also includes og:image and twitter:image. This site sets neither image key, so the output above has no image tags.

Sitemap

Hugo automatically generates the sitemap. For a multilingual site, it generates an index:

the structure under public/
sitemap.xml        ← the index, pointing at the two below
en/sitemap.xml
zh/sitemap.xml

Both the site default and per-page overrides are Hugo’s own:

hugo.yml
sitemap:
  changefreq: monthly
  filename: sitemap.xml
  priority: 0.5
one page
---
title: Release notes
sitemap:
  priority: 0.8
---

changefreq and priority are hints. A search engine may ignore them. Before publishing, confirm that the sitemap excludes drafts, private content, and non-canonical copies. Confirm that Hugo generated a file for each language.

robots.txt and staying unindexed

Hugo generates robots.txt only when the site configuration turns it on:

hugo.yml
enableRobotsTXT: true

The theme’s template generates one of two results, based on the build environment. You do not need to write the content:

a production build
User-agent: *
Allow: /

Sitemap: https://oink.pgsty.com/sitemap.xml
a non-production build
User-agent: *
Disallow: /

The page’s robots meta tag uses the same switch. It emits index, follow in production, except in print output. Otherwise, it emits noindex, nofollow. Do not build preview deployments with --environment production. A non-production build automatically requests no indexing.

The theme has no per-page noindex switch. To reliably prevent indexing, do not publish the page. Use draft: true or Hugo’s _build options. If you must publish it and request no indexing, emit your own tag through the head-end.html hook. The theme already emits one robots meta tag. Each search engine decides how to interpret two tags.

Checking indexing

One or two weeks after launch, check the following items in order. Confirm that search engines see the expected site:

  1. Crawl permission: open <baseURL>/robots.txt. Confirm that it contains Allow: / instead of Disallow: /.
  2. Page inventory: open <baseURL>/sitemap.xml. Open a language sitemap from the index and check the page count.
  3. Indexed count: search site:yourdomain. Check the order of magnitude. You do not need to compare every page.
  4. Canonical addresses: confirm that results open the canonical URL. They should not use a ? parameter or an old domain.
  5. Active submission: add the site in Google Search Console / Bing Webmaster Tools. Submit the sitemap.xml address to request crawling sooner.

Verify

Run from your site’s root. Replace PAGE with a generated page on your site, including any language prefix:

Terminal
hugo --gc --minify --printPathWarnings
PAGE=public/docs/getting-started/index.html
test -f "$PAGE"

# Canonical should use the real production address; production robots allow indexing.
grep -o '<link[^>]*canonical[^>]*>' "$PAGE"
grep -o '<meta[^>]*robots[^>]*>' "$PAGE"
cat public/robots.txt
head -5 public/sitemap.xml

# No match is expected when Google Analytics is not configured.
grep -o '<script[^>]*googletagmanager[^>]*>' "$PAGE"

In the browser’s Network panel, confirm that configured analytics requests use your measurement ID or registered domain. Repeat this check on a deployment built with --environment staging. It should make no analytics request. If you configured no analytics, neither environment should make an analytics request. Other explicitly enabled integrations may still contact their remote services.

  • Deploy — baseURL, the checklist, and keeping preview deployments unindexed
  • Repository links and page info — the feedback widget, edit links and last-modified time
  • Languages — language configuration decides hreflang and translation pairing
  • AI-agent support — the .md output and llms.txt written for models
  • Configuration — services, sitemap, enableRobotsTXT and the rest