Analytics and SEO
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:
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:
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.
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:
For Plausible, replace your-site.example with the domain registered in your
own account before adding this hook:
Do not omit the hugo.IsProduction guard. Without it, each local preview sends
reports to your analytics service.
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:
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:
- The page’s
descriptionfront matter - The page summary Hugo computes (
.Summary) params.descriptionin 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.
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:
canonical and hreflang
The theme emits one canonical link per page and hreflang alternate links for
actual translations. No configuration is required:
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:
To give a shared link an image, set images in front matter:
For a site-wide fallback, write the same key under params:
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:
Both the site default and per-page overrides are Hugo’s own:
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:
The theme’s template generates one of two results, based on the build environment. You do not need to write the content:
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:
- Crawl permission: open
<baseURL>/robots.txt. Confirm that it containsAllow: /instead ofDisallow: /. - Page inventory: open
<baseURL>/sitemap.xml. Open a language sitemap from the index and check the page count. - Indexed count: search
site:yourdomain. Check the order of magnitude. You do not need to compare every page. - Canonical addresses: confirm that results open the canonical URL. They should not use a
?parameter or an old domain. - Active submission: add the site in Google Search Console / Bing Webmaster Tools. Submit the
sitemap.xmladdress to request crawling sooner.
Verify
Run from your site’s root. Replace PAGE with a generated page on your site,
including any language prefix:
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.
Related
- 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
hreflangand translation pairing - AI-agent support — the
.mdoutput andllms.txtwritten for models - Configuration —
services,sitemap,enableRobotsTXTand the rest