Override canonifyURLs in outputFormats?

support
1

I’m creating a second output format to generate HTML files that will eventually be sent via email, along with the regular version of the site that is rendered the usual way. Working from the suggestions here, I’ve created a section in my config.toml that looks like this:

[outputFormats]
  [outputFormats.HTMLEmail]
    name = "HTMLEmail"
    path = "html_email"
    mediaType = "text/html"
    isHTML = true
    canonifyURLs = true # this doesn't work

The rest of the site uses the default canonifyURLs = false. What I want to do is have any URLs in the email version be fully canonified. For example, so an <img src > points back to the mothership. But as I have it above, it doesn’t work. The HTML files to be emailed use the same relative URLs the main site does.

What’s the right way to get the behavior I want? I’d rather not have to canonify the regular website, too.

2

You could try piping your URLS through absURL ?

3

Hi, if your HTML has a meta section, add

<base href={{ site.BaseURL }} />

4

I don’t think that will work. I store all my images under the static directory, and not with the posts, so their URL’s all start with “/” and my understanding is that base href only works with relative URL’s. Maybe I’m doing it wrong.

5

You mean at every point in my content where I have an <img src>?

6

If it’s specifically markdown / content images, you can use render hooks.

7

You should read the documentation:

There is a noUgly option on Output formats, meaning you can turn it off (if it’s on).

8

With all due respect, I spent about 12 hours in the documentation over the course of the past week and didn’t get anywhere. It’s a poorly organized circular trainwreck. I wouldn’t have come to the forum unless I felt I was out of options.

To your specific suggestion, that didn’t make a difference, but thanks.

9

Let me add more detail.

I generally add images to my content with something like:

{{< figure src="/2020/img/IMG_0384.JPG" >}}

That /2020 is a subdirectory immediately under static. If I don’t prefix that image path with the /, hugo wants to look in the directory where the md file is. But it’s not there. I want to keep my images in the same place.

If I set canonifyURLs = true, then every URL in the generated HTML comes out correctly, both for the normal site and the email renderings. If that’s the solution, then so be it. That feels like a big sledgehammer that might have side effects, but I’ll live with it if I have to.

10
  1. If you had read the docs you would have seen that canonifyURLs is not a configuration option for custom output formats.
  2. Of course you need to start your src path with a / if you have your images in static. That’s how html filepaths work. Without it, it will look for your image in the current directory, and as you said it is not there.
  3. Since you are using a shortcode to add images, my first suggestion stands, with an addition: modify the shortcode and pipe the url through absURL.
11

Quote:

Protocol-relative links (PRL), also known as protocol-relative URLs (PRURL), are URLs that have no protocol specified. For example, //example.com will use the protocol of the current page, typically HTTP or HTTPS

/2020/img/IMG_0384.JPG is an relative URL!

12

Calling other people’s work for a trainwreck does not sound respectful to me.

A tip for using the documentation would be to use the search (which I think is pretty good):

  • Search for “ouput format” would take you Custom output formats | Hugo
  • There is a section called “Configure Output Formats”
  • In this section, you would find the relevant information.

A general tip about software configuration is that guessing almost never works.

1 Like
14

While I agree that it is unfriendly to call the documentation a trainwreck, I think the text really leaves a lot to be desired. I’m not knowledgeable enough to write anything, but I noticed some general aspects that could be amended.

  • The author(s) should have a clear idea of their target group for the documentation. Or rather, for the different kinds of documentation.
  • Different kinds, because right now, there are greatly differing approaches: reference manual, mini-tutorial, description, examples …
  • More experienced people need a reference
  • Beginners would benefit from an introduction along the lines
    • installation
    • write your first page
    • see your first page in the browser: write your first very simple template
    • how are the different types of pages (single/list) playing together, which templates do you need
    • what are page bundles, why do you need/want them
    • what are taxonomies, why do you need/want them
  • Intermediate learners might want to read about asset pipelines and other more advanced subjects

Actually, the part on assets and pipes on the documentation is a good illustration for possible amendments: It never really states what an “asset” is. So one starts reading without knowing what it all is about and then possibly stops, because the relevance is not made clear from the start. Starting out with something like “Assets can be CSS and JavaScript files that you want to use on your site. They might need special handling like minifying or purging unused code for performance reasons or you want to generate your CSS from SASS. For these purposes, Hugo provides pipes…” (admittedly, my wording is less than perfect)

Another example where the documentation is not very helpful is ref | Hugo. It lists about 10 different uses of ref, but not a single result of these usages. I’m sorry to say, but this kind of example is useless: Most everybody will know how to write ref "someurl" – the interesting point is the result this function and/or shortcut produces.

I don’t mean my comments to be disrespectful – writing all these things takes a lot of time and effort, and I appreciate that. But since there are quite some people who complain about the documentation, it might be worthwhile to think about possible amendments. With which I’d be willing to help, but currently I do not have even the slightest idea where to start. Also, better documentation eases the burden on the forum :wink:

15

Trust me it doesn’t. People don’t read the documentation. Read recent posts here that have less than 3 answers and count how many of these posts are answered with a link to the docs and answered by “Oh, didn’t see this”.

The problem with an open source project that hit’s some kind of threshold as Hugo did around 2 years ago is that the usership changes from a “bunch of nerds” to “everyone reading an article on a famous blog and starting to use it”. This can be proven by just reading the posts on this discourse. These days the posts that want a “dynamic” website which has nothing to do with a static website generator are daily and basically overpower the resources of UNPAID workers that try to help.

I myself regularly receice messages that would want me to stop answering anything here, but I kind of still try to filter the normal people from “them”. I also like to be abused. Obviously.

FACT: “Open as in Open Source” does not mean you (the user) have the right to abuse anybody who tries to help. It also does not mean you have a paid callcenter at your disposal to help with anything from unread documentation to feature requests that do not exist in this universe.

You wouldn’t buy a Mercedes to listen to a cassette tape.

50% of the people who write here on the discourse have NOT read the docs and expect people to answer their request, because Hugo is FREE. They DO NOT understand open source.

Having said that: If you find a way to optimise the documentation for ref I will personally merge your commit preferred. The way to start is load the page in the documentation that you want to change, then click the edit link at the bottom. Just add a note to @davidsneighbour in your commit at Github. I myself did this kind of things often after reasonably pushy asking here on discourse about it. The way to win is to ask without starting your sentence with “your docs are crap”.

What Hugo needs is a team of non-developers writing the documentation. But that is not how it historically grew. I stopped saying that because people frowned upon it, but there is a lot of people using Hugo that should just (<<< there, a trigger word) go to use WordPress.

As long as Hugo’s version number starts with a 0, people should not assume to have a finished polished well documented product.

Open source is like these “take one, leave one” coin exchanges at your mum-and-pop-stores at the corner. And criticising WITHOUT an attempt to do it better never helps.

And reopening an opinion piece 9 months after it happened? Muahaha.