New official Go template formatter for VS Code

Announcements
1

See gotmplfmt - Visual Studio Marketplace

For those who don’t use VS Code, there’s a standalone CLI avalable at GitHub - gohugoio/gotmplfmt: Work in progress. · GitHub

3

Apologies for my ignorance, but would like to highlight two things about it.

Received email about “New official Go template formatter for VS Code” and been excited to see what it is and how this will help me.

Sadly, I struggle to understand from reading notes on Marketplace or GitHub, what it is, what it does and how it can benefit myself and others.

I do not doubt that I am not the only one, looking at number of installs been low.

The core idea of this extension is great, and I think everybody who working with Hugo in VS Code shall have this extension installed.

Because I will be not the only one who struggle to understand this, I get the below (using Gemini). Hope this will help and will make this extension much more popular among Hugo’ers.

What it is

gotmplfmt is a brand-new, official code formatter built by the core Hugo team specifically for Go templates. It consists of two parts: a command-line tool, and a VS Code extension that connects that tool to your editor.

The Problem it Solves

Hugo builds its web pages using Go templates (the {{ ... }} tags you write inside your .html files). Historically, editing these files in VS Code has been frustrating because standard HTML formatters (like Prettier or VS Code’s built-in formatter) do not understand Go template logic. If you ran a standard formatter, it would often break your layout, misalign your {{ if }} and {{ end }} statements, or jumble your code.

Previously, the Hugo community had to rely on a third-party plugin called prettier-plugin-go-template. However, that tool was abandoned years ago and had several bugs. The Hugo team created gotmplfmt to be the official, modern replacement.

What it does (Before & After)

When you trigger formatting in VS Code (or save your file), gotmplfmt automatically organizes your code, fixing the spacing and indentation for both the HTML tags and the Hugo logic.

Before formatting:

<nav>
<ul>
{{range .Site.Menus.main}}
<li>
<a href="{{.URL}}">{{.Name}}</a>
</li>
{{end}}
</ul>
</nav>

After gotmplfmt runs:gotmplfmt

<nav>
  <ul>
    {{ range .Site.Menus.main }}
      <li>
        <a href="{{ .URL }}">{{ .Name }}</a>
      </li>
    {{ end }}
  </ul>
</nav>

How this is useful to you when managing Hugo sites

  • Saves Time: You no longer have to manually hit the spacebar to line up your nested loops ({{ range }}) and conditionals ({{ if }}).

  • Fewer Errors: Properly indented logic makes it significantly easier to spot a missing {{ end }} tag, which is one of the most common causes of Hugo build errors.

  • Official Support: Because it is built by the people who make Hugo, it is designed to seamlessly handle all of Hugo’s built-in functions, shortcodes, and embedded templates without breaking.

A Quick Note on Setup

If you decide to use it in VS Code, simply installing the extension is not quite enough. The extension relies on the actual Go program running on your computer.

On macOS with Brew

brew install go

You will first need to ensure you have Go installed on your machine, and then run go install github.com/gohugoio/gotmplfmt@latest in your terminal so the VS Code extension has the engine it needs to format your files.

you may also need to Configure Path where it is installed in the extension settings, like: /Users/USERNAME/go/bin/gotmplfmt

Also, after:

Set gotmplfmt as your Default Formatter

You need to tell VS Code to prioritise the new Hugo formatter for your HTML files.

  1. Open your template file, like head.html file in VS Code.

  2. Open the Command Palette by pressing Cmd + Shift + P on your Mac.

  3. Type Format Document With… and hit Enter.

  4. A dropdown menu will appear. Click on Configure Default Formatter… at the bottom of that list.

  5. Select gotmplfmt from the list of options.

From now on, whenever you right-click and select “Format Document” (or press Shift + Option + F), it will use the correct Hugo formatter to tidy up your code.

Magic! :tada:

Hope that helps.

4

I have “format on save” enabled.

5

I have added some alternative ways to install this without having to have Go installed:

.

6

I was also kinda lost when I saw the announcement and had to end up here to understand what I am trying to do.

7

Tried it briefly, but on existing .html files it appears to kill syntax highlighting (i.e., everything’s just white text on black, in the case of the theme I’m using). Or am I just doing something wrong?

Edit: I should note this was before I read the instructions above from @idarek — whereas what I’d done was to open an .html file and, in the bottom bar of VS Code, use the “File Association” pop-up. I’d guess that was my problem, but will wait to see whether others can correct me further.