Hugo theme: govanity (vanity URLs for Go modules / packages with Hugo)

The govanity Hugo theme simplifies building and maintaining a vanity base domain such as go.example.com or example.dev and serving the required <meta> tags for vanity import paths.

The generated static site can be deployed on any static-capable host. The landing page lists all modules; each module is a content file with fitting front matter. See archetypes/default.md for a ready-to-use template.

Table of contents

• Why vanity import paths?
• Demo
• Installation
  • Using Hugo modules
  • Using Git submodules
• Configuration
  • Settings
    • vanityPageTags
    • header.logo
    • header.showTitle
    • header.title
    • footer.additionalText
    • footer.additionalTextTrailingBreak
    • footer.showThemeInfo
    • footer.showTrademarksInfo
    • footer.showGoGopherInfo
• Usage
  • Creating new entries
  • Deployment
• Compatibility
• Contributing
• Troubleshooting
• Licensing, copyright
• Author information

Why vanity import paths?

By default, Go imports point to repository hosts, e.g.:

import "github.com/user-or-org/foo"

Vanity import paths decouple the import path from the code host. For example, the module hugo-theme-dev can be imported as:

import "golang.foundata.com/hugo-theme-dev"

Under the hood, the site serves <meta name="go-import" ...> that redirect tooling to the real repository (e.g. GitHub).

Further reading, references:

• Vanity import paths in Go by Márk Sági-Kazár
• Using Go Vanity URLs with Hugo by Jessica Bowen
• go docs: Remote import paths

Demo

Clone the repository and run the included example content (requires Hugo, Go, and Git):

git clone https://github.com/foundata/hugo-theme-govanity.git
cd ./hugo-theme-govanity/exampleSite
HUGO_MODULE_WORKSPACE=hugo.work hugo server --ignoreVendorPaths "**"

Or look at the following pages using this theme:

• https://golang.foundata.com/

Installation

Using Hugo modules

Add the following module path(s) to your theme: configuration:

theme:
  - "golang.foundata.com/hugo-theme-govanity"

Hugo automatically fetches and import theme module paths as Go/Hugo modules, so you do not need to list them under module.imports manually. Using modules requires Hugo, Go, and Git to be installed on your system.

Using Git submodules

From the root directory of your Hugo site, initialize a new Git repository (if you haven't already), then add the theme as a Git submodule:

git submodule add https://github.com/foundata/hugo-theme-govanity.git themes/govanity

Now reference the theme directory name in your theme: configuration:

theme:
  - "govanity"

Configuration

Set your vanity base URL in the Hugo config (this must be the (sub)domain that serves your vanity paths) and disable unsupported page kinds:

baseURL: "https://go.example.com/"

# Single-purpose theme; exact request URIs are critical.
# Disable features that could alter URLs or produce needless pages:
# - Unsupported page kinds
# - Multilingual/i18n (interferes with Go vanity import path matching)
disableKinds:
  - "rss"
  - "section"
  - "taxonomy"
  - "term"
defaultContentLanguageInSubdir: false

ℹ️ Heads-up: Exact host + path matters to the Go toolchain. Use HTTPS and avoid extra path segments in baseURL. Do not forget the trailing slash.

Settings

This section documents the theme options you can place under params.theme in your Hugo configuration. The example configurations and are safe to copy-paste. All keys are optional and the theme falls back to sensible behavior unless otherwise noted.

⚠ Easy adaption of colors is not implemented yet (see Issue #6). Coming releases will provide this, stay tuned.

vanityPageTags

• Type: List of strings.
• Default: ["go-module"]
• Purpose:
  • Only content pages that define at least one of these tags in their Front Matter are treated as vanity module pages (included in the overview and get the go-import / go-source meta tags emitted early).
  • Put the tags in each module page's Front Matter under tags:.
• Example (config):

  params:
    theme:
      vanityPageTags:
        - "go-module"
        - "hugo-module"

• Example (page Front Matter):

  ---
  title: "hugo-theme-dev"
  tags:
    - "go-module"
    - "hugo-module"
  repo:
    root: "github.com/foundata/hugo-theme-dev"
  ---

header.logo

• Type: Object with src, optional width, optional height.
• Default: Not set.
• Purpose:
  • Show a logo in the header.
  • src is a relative path under /assets (e.g., images/logo.svg).
  • width and height become <img> attributes (strings), letting you control layout.
• Example (config):

  params:
    theme:
      header:
        logo:
          # This image is shipped with the theme
          src: "images/logo-go-gopher-network.svg"
          width: "40"
          height: "35"

header.showTitle

• Type: Boolean.
• Default: true
• Purpose:
  • Toggle a text title in the header (rendered next to the logo if a logo is set).
  • If enabled, the theme displays either header.title or falls back to .Site.Title.
• Example (config):

  params:
    theme:
      header:
        showTitle: true

header.title

• Type: String.
• Default: Not set.
• Purpose:
  • Used only if header.showTitle is true. If empty or unset, the theme uses .Site.Title.
  • Explicit header title as kind of text logo
• Example (config):

  params:
    theme:
      header:
        showTitle: true
        title: "Go import path overview"

footer.additionalText

• Type: String.
• Default: ""
• Purpose:
  • Optional extra text in the footer. Markdown is allowed (but raw HTML will be filtered).
  • If empty, no extra text is rendered.
• Example (config):

  params:
    theme:
      footer:
        additionalText: "© 2025 AMCE Inc. | [Contact Us](https://exmaple.com/contact)"

footer.additionalTextTrailingBreak

• Type: Boolean.
• Default: true
• Purpose:
  • Add a line break after additionalText.
  • Useful if the line gets too long when combining additionalText with attribution toggles below.
• Example (config):

  params:
    theme:
      footer:
        additionalText: "© 2025 AMCE Inc. | [Contact Us](https://exmaple.com/contact)"
        additionalTextTrailingBreak: true # will add a <br> after the additional text

footer.showThemeInfo

• Type: Boolean.
• Default: true
• Purpose: Show a short theme attribution link in the footer.
• Example (config):

  params:
    theme:
      footer:
        showThemeInfo: true

footer.showTrademarksInfo

• Type: Boolean.
• Default: true
• Purpose: Show a link to Google's Go Brand and Trademark Usage Guidelines (recommended).
• Example (config):

  params:
    theme:
      footer:
        showTrademarksInfo: true

footer.showGoGopherInfo

• Type: Boolean.
• Default: true
• Purpose: Show attribution information about the Go Gopher (recommended).
• Example (config):

  params:
    theme:
      footer:
        showGoGopherInfo: true

Usage

Creating new entries

Add a new Markdown file directly under the content root for each module (no nested folders). For example:

content/hugo-theme-dev.md

You can use the provided archetype to scaffold the front matter:

hugo new hugo-theme-dev.md
# or explicitly: hugo new --kind default hugo-theme-dev.md

Below is the minimal set you'll typically use (see archetypes/default.md for the full, annotated version):

---
title: "hugo-theme-dev"
tags:
  - "go-module"
  - "hugo-module"
repo:
  root: "github.com/foundata/hugo-theme-dev"
---

The theme emits <meta name="go-import"> (and optionally <meta name="go-source">) very early in the page <head> as recommended by Go's docs. The single package page also shows helpful commands and links for humans.

Deployment

This is a static site: deploy anywhere you can host static files (e.g. your small VM, GitHub Pages, Netlify, Cloudflare Pages, S3 + CDN). Ensure:

1. The site is served at your baseURL host (e.g., https://go.example.com/).
2. Requests like https://go.example.com/hugo-theme-dev?go-get=1 return HTML that includes the go-import meta tag.
3. Avoid JavaScript/CSS before the meta tag in <head> (the theme already places it first).

Troubleshooting

• no go-import meta tags: Verify the request path and that the HTML contains the correct <meta name="go-import" ...> tag. Try visiting the page with ?go-get=1.
• Module not listed on the overview: Check the page tags and params.handleTags.
• Imports still point to the old host: Clear module cache (go clean -modcache) and ensure DNS/HTTPS and exact paths are correct.

Compatibility

This project is compatible with Hugo (extended) ≥ v0.148.0 and should always work with the latest Hugo release (we usually run the latest Hugo ourselves and fix issues promptly). It has been tested at least with:

• Hugo extended v0.149.0
• Hugo extended v0.148.0

If your version isn't listed, it might still work. Just give it a try.

Contributing

See CONTRIBUTING.md if you want to get involved.

This projects's functionality is mature, so there might be little activity on the repository in the future. Don't get fooled by this, the project is under active maintenance and used daily by the maintainers.

Licensing, copyright

Copyright (c) 2025 foundata GmbH (https://foundata.com)

This project is licensed under the GNU General Public License v3.0 or later (SPDX-License-Identifier: GPL-3.0-or-later), see LICENSES/GPL-3.0-or-later.txt for the full text.

The REUSE.toml file provides detailed licensing and copyright information in a human- and machine-readable format. This includes parts that may be subject to different licensing or usage terms, such as third-party components. The repository conforms to the REUSE specification. You can use reuse spdx to create a SPDX software bill of materials (SBOM).

Author information

This project was created and is maintained by foundata.