Breaking changes in v0.148.0

Overview

We’ve resolved three long-standing bugs in v0.148.0 (releasing later this week) that affected page publication paths and the values returned by the Permalink and RelPermalink methods on Page objects.

Issue Trigger
#4428 uglyURLs is true
#7497 uglyURLs is true
#13829 Output format definition includes a path parameter

As the “Trigger” column shows, these bugs and their corresponding fixes only apply under a narrow set of conditions.

With these corrections, affected pages are now published to the correct paths, and the Permalink and RelPermalink methods on their corresponding Page objects now return accurate values. Because the URLs of some pages have changed, these are considered breaking changes, but only under the specific conditions outlined above.

Rather than diving into detailed issue descriptions, it’s probably clearer to show you some visual examples.

Issues #4428 and #7497

With this content structure:

content/
├── s1/
│   ├── _index.md
│   └── p1.md
├── tags/
│   ├── red/
│   │   └── _index.md
│   └── _index.md
└── _index.md

And this site configuration

baseURL = 'https://example.org/'
title = 'Testing'
languageCode = 'en-US'
disableKinds = ['rss','sitemap']

uglyURLs = true # triggers #4428 and #7497

[taxonomies]
tag = 'tags'

Prior to v0.148.0 Hugo published the site like this:

public/
├── s1/
│   └── p1.html   <-- RelPermalink: /s1/p1.html
├── tags/
│   └── red.html  <-- RelPermalink: /tags/red.html
├── index.html    <-- RelPermalink: /              (bug #7497)
├── s1.html       <-- RelPermalink: /s1.html       (bug #4428)
└── tags.html     <-- RelPermalink: /tags.html     (bug #4428)

With v0.148.0 and later Hugo publishes the site like this:

public/
├── s1/
│   ├── index.html  <-- RelPermalink: /s1/index.html
│   └── p1.html     <-- RelPermalink: /s1/p1.html
├── tags/
│   ├── index.html  <-- RelPermalink: /tags/index.html
│   └── red.html    <-- RelPermalink: /tags/red.html
└── index.html      <-- RelPermalink: /index.html

When paginating a page collection, the pager URLs will change from something like this:

http://example.org/posts/page/3/  <-- (bug #4428)

To this:

http://example.org/posts/page/3/index.html

Also note that “serverless” sites are now easier to create.

Issue #13829

With this content structure:

content/
├── s1/
│   ├── _index.md
│   └── p1.md
├── tags/
│   ├── red/
│   │   └── _index.md
│   └── _index.md
└── _index.md

And this site configuration

baseURL = 'https://example.org/'
title = 'Testing'
languageCode = 'en-US'
disableKinds = ['rss','sitemap']

[taxonomies]
tag = 'tags'

[outputFormats.print]
isPlainText = true
mediaType = 'text/plain'
path = 'print' # triggers #13829
permalinkable = true
ugly = true

[outputs]
home = ['html','print']
page = ['html','print']
section = ['html','print']
taxonomy = ['html','print']
term = ['html','print']

Prior to v0.148.0 Hugo published the site like this:

public/
├── print/
│   ├── s1/
│   │   └── p1.txt      <-- RelPermalink: /print/s1/p1.txt
│   └── index.txt       <-- RelPermalink: /print/index.txt
├── s1/
│   ├── p1/
│   │   └── index.html  <-- RelPermalink: /s1/p1/
│   ├── index.html      <-- RelPermalink: /s1/
│   └── print.txt       <-- RelPermalink: /s1/print.txt       (bug #13829)
├── tags/
│   ├── red/
│   │   ├── index.html  <-- RelPermalink: /tags/red/
│   │   └── print.txt   <-- RelPermalink: /tags/red/print.txt (bug #13829)
│   ├── index.html      <-- RelPermalink: /tags/
│   └── print.txt       <-- RelPermalink: /tags/print.txt     (bug #13829)
└── index.html          <-- RelPermalink: /

With v0.148.0 and later Hugo publishes the site like this:

public/
├── print/
│   ├── s1/
│   │   ├── index.txt   <-- RelPermalink: /print/s1/index.txt
│   │   └── p1.txt      <-- RelPermalink: /print/s1/p1.txt
│   ├── tags/
│   │   ├── index.txt   <-- RelPermalink: /print/tags/index.txt
│   │   └── red.txt     <-- RelPermalink: /print/tags/red.txt
│   └── index.txt       <-- RelPermalink: /print/index.txt
├── s1/
│   ├── p1/
│   │   └── index.html  <-- RelPermalink: /s1/p1/
│   └── index.html      <-- RelPermalink: /s1/
├── tags/
│   ├── red/
│   │   └── index.html  <-- RelPermalink: /tags/red/
│   └── index.html      <-- RelPermalink: /tags/
└── index.html          <-- RelPermalink: /
2 Likes