CanonifyURLs & RelativeURLs interaction

support
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