The jollyroger static site generator is a single Go file using only the standard library. It runs five live sites. Most of their sister sites run on Hugo, and posts get copied from one to the other. The trouble was addresses. jollyroger couldn’t make one from a title, and where Hugo keeps a dot or a plus sign in a URL, jollyroger turned it into a hyphen or dropped it. A copied post could land at a different address, and the tags “C” and “C++” would share one page.
The job was to build the address Hugo 0.147 builds from any title, tag, url or alias, special characters included, without moving a single live URL.
Porting Hugo’s Rules to Go
Working from Hugo’s source, about 350 new lines of Go now take the same steps, with Hugo’s permalinks patterns (:title, :slug, :year and more) as a new, optional setting. The five sites leave it off, so their file names still decide their addresses. Addresses go out escaped as Hugo writes them (krak%C3%B3w for kraków), and front matter is read as Hugo reads it.
Where Hugo itself breaks, jollyroger does the safe thing. A title of only symbols, like ???, overwrites the homepage in Hugo; here it gets the file name’s address and a warning. A url or alias with %20 in it, or a tag like 100%41, gets a folder in Hugo that its own link misses, and here it works. A 140-letter Hebrew title stops a Hugo build with “file name too long”; jollyroger shortens the folder name instead.
Hugo as the Answer Key
About 100 titles and tags, some from live posts, went through real Hugo builds, and Hugo’s answers became the expected values in the Go tests. A harness then built the same content with Hugo 0.147.9 and with jollyroger and compared where every page, tag page and redirect landed. On 123 test pages with awkward titles and addresses, 121 matched, and every difference was one of the fixes above. On 22 live Hugo sites, all 2,396 posts and pages and 1,411 tag pages matched.
The harness paid for itself. Its first run on real sites stopped on two that Hugo builds fine, one with a blank line before the front matter and one with a space after the opening ---. It showed that tags need a space-to-hyphen step of their own, and twice real Hugo proved our own expected values wrong. KeyValueStore’s tools were checked the same way, against real Redis, Valkey, DynamoDB Local and etcd where a server applies.
Five Sites, No Moved URLs
Each site was built with both engines. File lists matched on all five, and three came out byte for byte the same. On the other two, one tag’s address (cafés on one, Kraków on the other) is now written in Hugo’s escaped form. All 238 post and page addresses stayed put. The update reached all five sites on 14 October, after each passed its build and tests.
A new site that wants title-based URLs now needs one line in its config.