Improve publishing path when the output format "path" is set

[jmooring]

This isn't anything new. The behavior described below is present in v0.73.0 and later, and probably well before that. Anything we do here will be a breaking change, limited to those sites where path is specified in one or more of its output format definitions.

Important

Since this change is going to break some eggs, I strongly suggest we address #4428 and #7497 at the same time.

---

Our documentation describes the output format path setting as follows¹:

The published file’s directory path, relative to the root of the publish directory. If not specified, the file will be published using its content path.

However, the actual behavior is very different.

Consider this site configuration:

uglyURLs = false

[outputFormats.print]
isPlainText = true
mediaType = 'text/plain'
path = 'print'

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

[taxonomies]
tag = 'tags'

And this content structure:

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

When you build the site, the URL pattern of the "print" output format depends on the page kind, which doesn't make sense:

page kind	content path	published path
page	content/s1/p1.md	public/print/s1/p1/index.txt
section	content/s1/_index.md	public/s1/print/index.txt
taxonomy	content/tags/_index.md	public/tags/print/index.txt
term	content/tags/red/_index.md	public/tags/red/print/index.txt
home	content/_index.md	public/print/index.txt

Or to look at the entire structure:

tree

public/
├── print/
│   ├── s1/
│   │   └── p1/
│   │       └── index.txt
│   └── index.txt
├── s1/
│   ├── p1/
│   │   └── index.html
│   ├── print/
│   │   └── index.txt
│   └── index.html
├── tags/
│   ├── print/
│   │   └── index.txt
│   ├── red/
│   │   ├── print/
│   │   │   └── index.txt
│   │   └── index.html
│   └── index.html
└── index.html

My expectation is that the URL pattern would be the same² regardless of page kind.

Test site that matches the above:

git clone --single-branch -b hugo-github-issue-13829 https://github.com/jmooring/hugo-testing hugo-github-issue-13829
cd hugo-github-issue-13829
rm -rf public/ && hugo && tree public

We need test cases with and without uglyURLs enabled.

References:

• https://discourse.gohugo.io/t/custom-outputformat-path-and-index-md-files/55215
• https://discourse.gohugo.io/t/published-path-of-alternate-output-formats/35695/13
• Hugo with uglyURLs = true generates /public/section.html instead of /public/section/index.html #4428
• Output format with custom path on section pages - Image paths broken #7342
• resources/page: Fix custom output formats path for sections and taxonomies #7771
• Output format (AMP) prefix is getting put after sections and taxonomies #7159

Footnotes

1. This could use some fine tuning, perhaps: "The initial directory segment for the published file. This path is relative to the root of your publication directory. If omitted, Hugo will use the file's original content path for publishing." ↩

2. It should match the existing documentation. ↩

[jmooring]

Integration test:

func TestIssue13829(t *testing.T) {
	t.Parallel()

	files := `
-- hugo.toml --
uglyURLs = false

[outputFormats.print]
isPlainText = true
mediaType = 'text/plain'
path = 'print'

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

[taxonomies]
tag = 'tags'
-- content/_index.md --
---
title: home
---
-- content/s1/_index.md --
---
title: s1
---
-- content/s1/p1.md --
---
title: p1
tags: ['red']
---
-- content/tags/_index.md --
---
title: tags
---
-- content/tags/red/_index.md --
---
title: red
---
`

	templates := []string{
		"layouts/home.html",
		"layouts/home.print.txt",
		"layouts/page.html",
		"layouts/page.print.txt",
		"layouts/section.html",
		"layouts/section.print.txt",
		"layouts/taxonomy.html",
		"layouts/taxonomy.print.txt",
		"layouts/term.html",
		"layouts/term.print.txt",
	}

	const code string = "TITLE: {{ .Title }} | AOFRP: {{ range .AlternativeOutputFormats }}{{ .RelPermalink }}{{ end }} | TEMPLATE: {{ templates.Current.Name }}"

	for _, template := range templates {
		files += "-- " + template + " --\n" + code + "\n"
	}

	b := hugolib.Test(t, files)

	// uglyURLs: false, outputFormat: html
	b.AssertFileContent("public/index.html", "TITLE: home | AOFRP: /print/index.txt | TEMPLATE: home.html")
	b.AssertFileContent("public/s1/index.html", "TITLE: s1 | AOFRP: /print/s1/index.txt | TEMPLATE: section.html")
	b.AssertFileContent("public/s1/p1/index.html", "TITLE: p1 | AOFRP: /print/s1/p1/index.txt | TEMPLATE: page.html")
	b.AssertFileContent("public/tags/index.html", "TITLE: tags | AOFRP: /print/tags/index.txt | TEMPLATE: taxonomy.html")
	b.AssertFileContent("public/tags/red/index.html", "TITLE: red | AOFRP: /print/tags/red/index.txt | TEMPLATE: term.html")

	// uglyURLs: false, outputFormat: print
	b.AssertFileContent("public/print/index.txt", "TITLE: home | AOFRP: / | TEMPLATE: home.print.txt")
	b.AssertFileContent("public/print/s1/index.txt", "TITLE: s1 | AOFRP: /s1/ | TEMPLATE: section.print.txt")
	b.AssertFileContent("public/print/s1/p1/index.txt", "TITLE: p1 | AOFRP: /s1/p1/ | TEMPLATE: page.print.txt")
	b.AssertFileContent("public/print/tags/index.txt", "TITLE: tags | AOFRP: /tags/ | TEMPLATE: taxonomy.print.txt")
	b.AssertFileContent("public/print/tags/red/index.txt", "TITLE: red | AOFRP: /tags/red/ | TEMPLATE: term.print.txt")

	files = strings.ReplaceAll(files, "uglyURLs = false", "uglyURLs = true")
	b = hugolib.Test(t, files)

	// The assertions below assume that https://github.com/gohugoio/hugo/issues/4428
	// and https://github.com/gohugoio/hugo/issues/7497 have been fixed.

	// uglyURLs: true, outputFormat: html
	b.AssertFileContent("public/index.html", "TITLE: home | AOFRP: /print/index.txt | TEMPLATE: home.html")
	b.AssertFileContent("public/s1/index.html", "TITLE: s1 | AOFRP: /print/s1/index.txt | TEMPLATE: section.html")
	b.AssertFileContent("public/s1/p1.html", "TITLE: p1 | AOFRP: /print/s1/p1.txt | TEMPLATE: page.html")
	b.AssertFileContent("public/tags/index.html", "TITLE: tags | AOFRP: /print/tags/index.txt | TEMPLATE: taxonomy.html")
	b.AssertFileContent("public/tags/red.html", "TITLE: red | AOFRP: /print/tags/red.txt | TEMPLATE: term.html")

	// uglyURLs: true, outputFormat: print
	b.AssertFileContent("public/print/index.txt", "TITLE: home | AOFRP: /index.html | TEMPLATE: home.print.txt")
	b.AssertFileContent("public/print/s1/index.txt", "TITLE: s1 | AOFRP: /s1/index.html | TEMPLATE: section.print.txt")
	b.AssertFileContent("public/print/s1/p1.txt", "TITLE: p1 | AOFRP: /s1/p1.html | TEMPLATE: page.print.txt")
	b.AssertFileContent("public/print/tags/index.txt", "TITLE: tags | AOFRP: /tags/index.html | TEMPLATE: taxonomy.print.txt")
	b.AssertFileContent("public/print/tags/red.txt", "TITLE: red | AOFRP: /tags/red.html | TEMPLATE: term.print.txt")
}

[bep]

@jmooring let me know if you want me to create a PR with a fix (I guess I know the code in question better). I will make sure that you will be credited as a "co author", as the test above certainly is more work than the fix itself.

[jmooring]

Yes please. It would take me a long time to figure this out.

[github-actions]

This issue has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.