CanonifyURLs & RelativeURLs interaction

support
1

PSA: CanonifyURLs and RelativeURLs interact with each other, and in particular if you use RelativeURLs=true, you may want to use CanonifyURLs=true also. If both are true, CanonifyURLs will not actually canonify all your relative urls…
It will however change the way the internal RelURL and adding context root to urls happens…

I wish I had known/seen this earlier because it works around some of the main problems I’d written about in my comments in the below linked topics.

I didn’t see this in the documentation, and only discovered it going through the source. Afterwards I did see other hints to this effect in other github issues and discussions here.

Background:
I’ve been trying for a while to figure out a “best practices” of sorts on how I could write themes/templates that have as little dependence on their final deploy location as possible.

Reference my comments in:


I will have to go back through my relative/absolute URL and function/property tests to see if this fixes all the unwanted behavior I was seeing, but if it does, I am not sure why one would ever use canonifyURLs=false and relativeURLs=true. Might be one of those traps due to unexpected interaction. I don’t know enough yet to say if this is the case and if relativeURLs=true should always have the behavior of canonifyURLs also being set vs. just having a note in the documentation about the effects.

2

I’ve had problems in this area as well.

As a (amateur) theme developer, I’ve been handling it by shipping a example config.toml with my theme(s). It includes comments explaining what knobs to adjust. See, for example:

# If your base url is not the site root, you must set canonifyURLs = "true"
# Example 1:
#   baseurl = "https://xyz.com/"
#   canonifyURLs = "false"
# Example 2:
#   baseurl = "https://xyz.com/spqr/"
#   canonifyURLs = "true"
canonifyURLs = "false"

Or this (note some horrible hacks to work around issues I had with URLs):

# If your base url is not the site root, you must set canonifyURLs = "true"
# Example 1:
#   baseurl = "https://xyz.com/"
#   canonifyURLs = "false"
# Example 2:
#   baseurl = "https://xyz.com/spqr/"
#   canonifyURLs = "true"
baseurl = "https://www.penwatch.net/ingress_guide/"
canonifyURLs = "true"

# To make website browseable offline, i.e. from local disk,
# set relativeURLs and uglyURLs to "true"
# see also params.ugly and params.uglyhome, below
relativeURLs = "true"
uglyURLs = "true"

[params]
    # set to "" if uglyURLs = "false"
    # set to ".html" if uglyURLs = "true"
    ugly = ".html"
    # set to "/" if uglyURLs = "false"
    # set to "/index.html" if uglyURLs = "true"
    uglyhome = "/index.html"

I couldn’t find any documentation that clearly explained the interaction between the config.toml settings:

  • relativeURLs
  • canonifyURLs
  • uglyURLs

And the various ways of handling URLs in themes:

  • $BaseURL
  • {{ "x" | relURL }}
  • {{ "x" | absURL }}
  • Page {{ .Permalink }}
  • Page {{ .URL }}
  • Menu item {{ .URL }} (handled differently to URLs in templates generally)

A concise guide RE: best practices for URL handling in themes, would be welcome! Particularly for sites that get deployed to a non-root folder (i.e. penwatch.net/cms) or that have to be browseable from a local filesystem.

3 Likes
3

@rdwatters could you shine some light on this? Canonify urls, relative urls, how when why? The docs give some information but not really the interactions between them and best use cases.

3 Likes