Getting Started

Install

Three install methods, ranked by recommendation.

Hugo extended 0.125 or newer is required. Check with hugo version — you want a build that says extended.

Pick your method #

Hugo Modules give you version-pinned installs and one-command upgrades. Requires Go 1.18+ for the one-time init.

bash 
# 1. Init your site as a Hugo Module (one time only)
hugo mod init github.com/your-org/your-site

# 2. Add the theme as a dependency
hugo mod get github.com/splunk/hugo-theme-splunk-workshop

Then in hugo.toml:

toml 
[module]
  [[module.imports]]
    path = "github.com/splunk/hugo-theme-splunk-workshop"

Pin to a release:

bash 
hugo mod get github.com/splunk/hugo-theme-splunk-workshop@v0.1.0

Update later:

bash 
hugo mod get -u

Which one?

Use Hugo Modules unless you have a strong reason not to — the version pin makes upgrades and CI deterministic. Submodule is fine for personal sites; direct download is fine for quick prototypes.

Minimal hugo.toml #

After installing the theme, this is the smallest config that produces a working site:

toml 
baseURL = "https://example.org/"
title   = "My Workshops"

# Pick ONE of the install methods above; this example uses a submodule.
theme = "hugo-theme-splunk-workshop"

[markup.goldmark.renderer]
  unsafe = true            # required for raw HTML in shortcode output

[outputs]
  home = ["HTML", "RSS", "JSON"]   # JSON powers client-side search

You’ll want to layer in [params] for branding once the basics work — see Customizing .

Verify it works #

bash 
hugo server

Open http://localhost:1313. You should see the theme’s default home with your site title. If something goes wrong, check the troubleshooting section below.

Troubleshooting #

Goldmark unsafe HTML

If shortcodes like card render as escaped text, you forgot unsafe = true under [markup.goldmark.renderer]. The theme emits raw HTML.

Search returns no results

The search modal needs home = ["HTML", "RSS", "JSON"] in your [outputs] block — the JSON output is the search index.

hugo: command not found

Install Hugo extended:

  • macOS: brew install hugo
  • Linux: download from gohugo.io/installation (the package manager versions are often outdated and not the extended build)
  • Windows: choco install hugo-extended
Last Modified ·