Building downloadable packages

Hi there!

I have a project containing:

  • /content/my-bundle/my-sub/img/my-pic.jpg
  • /content/my-bundle/my-sub/
  • /content/my-bundle/
  • /content/
  • config.toml

And in my-sub contains a relative reference to my-pic.jpg like this: ![My Pic](img/my-pic.jpg).

If I build it with hugo serve, it works. I can open the generated index.html for the my-sub page and it shows the picture.

Now, I want to provide it as a downloadable package, for offline viewing.

Out-of-box it will not work, since there are many absolute links - specially when using a theme.

I tried relativeURLs. It fixes all absolute links but it keeps links to folders. Those don’t work when opened locally.

When enabling uglyURLs, my-sub gets bundled as my-bundle/my-sub.html. Links work as intended, but the image is kept as my-bundle/my-sub/img/my-pic.jpg and referenced as img/my-pic.jpg which will not work.

Is there any recommended way of building offline pages? Or maybe force index.html when relativeURLs is used?

Does referencing your image as ![My Pic](./img/my-pic.jpg) work?

Using the ./ prefix? Unfortunately, no.

Our current workaround is using hugo serve then wget --mirror to create our downloadable bundle. It works incredibly well, but it would be good to have Hugo solving that problem without external actions.

You should look into the newly added Markdown Render Hooks. to edit those rendered images (and their URL) to your liking.

Note you will need to use the Goldmark markdown renderer (instead of Blackfriday). So might need to adjust a few things.

1 Like

What have you got baseURL set to in your config file? If this hugo server && wget process works, then maybe setting baseURL=localhost:1313 might work! (Or, I would assume baseURL = / if the site is going to be browsed locally.)

Unfortunately, we are using Asciidoc. I presume Render Hooks won’t help us.

How exactly baseURL would help? Maybe I need explain better our requirements. We want our users to be able to download a single file containing our manual. Originally, with Asciidoc, this would be a PDF. Right now, our manual is large enough to consider splitting it up. Hugo was chosen for the simplicity when on-boarding new contributors.

With Hugo, deployment to our online docs is trivial (call Hugo, upload files) and development is also easy (call Hugo, code, test in browser).

The offline copy is were I’m stuck. As an end result, downloading a compressed file and viewing with a browser is an acceptable trade-off to a single PDF, but we need images (screenshots) and having them per-page using Page Bundles would be more long-term than shoving them all into the static folder.

Unfortunately, all config flags combos I found has some impact on hugo server and on-line deployments, but none helps with out-of-box offline distribution. Closest so far was enabling both relativeURLs and uglyURLs into a different --environment for offline builds, but images does not work with that.

Therefore, that is why we went for the hugo serve & + wget workaround. hugo server works brilliantly for online previewing and wget also shines at mirroring arbitrary websites.