Convert a 0.16 site to modern Hugo syntax

support
1

A long time ago, I asked about a problem with a Hugo 0.16 site that failed when Hugo 0.18 came out. (See Site no longer renders with Hugo 0.18; now gives "LinkResolver: No page found for xxx" and 404 errors) The best workaround we could find was to force our build system to remain on Hugo 0.16.

Now, three years later, an upgrade to macOS Catalina makes hugo serve segfault, and we can’t build the site locally.

Question to the group: Is there a tutorial or documented process for bring an old (0.16) site forward to modern Hugo? You can see the current set of files at: https://github.com/tohojo/bufferbloat-net

Many thanks!

PS If you can help, we’ll tell you how to eliminate lag in your gaming and make the rest of your internet feel faster…

2

This is me in 5 minutes, but the site starts without errors and looks fine.

Have fun!

4 Likes
3

Thanks but no. Discussion in this forum must be kept on topic and the only topic is Hugo.

5

Oh dear. I am sorry to say that those suggested changes seem to be only part of the solution. The site now builds without errors.

But most of the internal links give 404 page not found errors. I think this is why we stuck with 0.16. (I seem to remember there was a significant change of semantics between 0.16 and 0.18…)

Here’s how our ~1,000 page site is structured. (For reference, you can see the file structure at https://github.com/tohojo/bufferbloat-net)

  1. We have several projects under our top-level home page. Each of those projects lives in a separate folder within the content directory.

  2. Each project directory contains three directories: a wiki directory for pages; a news directory for new posts, and an issues directory.

  3. Files within those directories are stored with obvious names, and a “.md” suffix.

  4. Links between other pages within the project are saved in Markdown format as some kind of path with or without a “.md” suffix:

    • [Tests for Bufferbloat](./Tests_for_Bufferbloat.md) or
    • [What Can I Do About Bufferbloat?](./What_can_I_do_about_Bufferbloat/) or simply
    • [glossary](Glossary.md)

  5. “Inter-project” links look like this: [wiki](/codel/wiki/index.md) That is, they start at project directory (codel) at the root of the server, then to its wiki directory to the target (with optional “.md” suffix)

So I renew my request for a tutorial or documentation for bringing the site into modern Hugo. Thanks again.

Update: For the record, here’s my current Hugo configuration, running on macOS Catalina 10.15.3…

bash-3.2$ brew install hugo
Warning: hugo 0.65.0 is already installed, it's just not linked
You can use `brew link hugo` to link this version.
bash-3.2$ brew link hugo
Linking /usr/local/Cellar/hugo/0.65.0... 38 symlinks created
bash-3.2$ hugo version
Hugo Static Site Generator v0.65.0/extended darwin/amd64 BuildDate: unknown
bash-3.2$ pwd
/Users/richb/github/bufferbloat-net
bash-3.2$ hugo serve

                   | EN
-------------------+------
  Pages            | 419
  Paginator pages  |   0
  Non-page files   | 156
  Static files     |  24
  Processed images |   0
  Aliases          |   6
  Sitemaps         |   1
  Cleaned          |   0

Built in 261 ms
Watching for changes in /Users/richb/github/bufferbloat-net/{archetypes,content,layouts,static}
Watching for config changes in /Users/richb/github/bufferbloat-net/config.yaml
Environment: "development"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/projects/ (bind address 127.0.0.1)
Press Ctrl+C to stop
6

There is no 0.16 to 0.50 upgrade guide, but I suspect you get very far if you rename all of your “index.md” to “_index.md”

7

That helps a tiny bit. Putting a “_” in front of “index.md” causes a link to /projects/bloat/wiki to display a list of the files in the directory. But there are still a couple problems/hassles:

  1. The file named “_index.md” (formerly "index.md) is not displayed in the list of files, nor does it seem to be accessible. How can I cause that page to be displayed?

  1. I still have a large number of Markdown-formatted internal links with this format (with or without “.md” suffix). The generated links still give 404’s - what should I do to fix them?

    [Tests for Bufferbloat](./Tests_for_Bufferbloat.md)

What advice can you give me for addressing these problems? Many thanks.

8

1 - look at the generated HTML and see what is the wrong link and why. Change accordingly your link in the .md
2 - look at the shortcodes ref & relref
3 - read the doc and understand what is the usage/meaning of _index.html

9

Thanks for your response. I played around with several variations of Markdown links and I think I understand what needs to happen.

But before I go editing the 2,000+ links in my site, I want to understand the rules.

Am I correct that in a Markdown link like [Tests for Bufferbloat](../tests_for_bufferbloat):

  • To access a file in the same folder, the link needs a "../" prefix?
  • The file name in the link must be all lower case (even if the file itself has a mixed-case file name)?
  • The “.md” suffix must not be present?

Thank you.

10

This topic hasn’t received any guidance on converting those early source files.

Consequently, we came up with a process (below) for building Hugo 0.16 on modern macOS. This will allow us to maintain our current source files and rebuild the site as needed.

Process for building Hugo 0.16 on macOS 10.15 (Catalina)

  • Upgrade to latest Go - https://golang.org/dl/ then double-click the .pkg file

  • Ensure that there are enough files: see https://medium.com/mindful-technology/too-many-open-files-limit-ulimit-on-mac-os-x-add0f1bfddde

  • Issue the following commands

    # Set the GOPATH to a directory outside the stock build path
export GOPATH=~/github/hugo-from-source
# save source in $GOPATH & build it from tohoho's git repo
# that contains a cached copy of Hugo 0.16 with correct dependencies
go get -v github.com/tohojo/hugo
# cd to the directory containing the Hugo source files
cd ~/github/bufferbloat.net
# run the newly-built hugo
$GOPATH/bin/hugo serve
11

Considering how old 0.16 is, you might be better off treating it as a “new” project.

Inspect each layout file to see if anything breaks. Using disableKinds might help, for example disabling all except home while you inspect the layouts/index.html.

No one is going to have a step-by-step guide for porting from 0.16 to 0.65.x because it’s just so old. There are intermediate guides in the changelog for when there are breaking changes in new versions.

edit:

So I’ve had a look at your repo, running on 0.65.3.

  • disableKinds all except homepage.
  • It will complain about .RSSLink, which has been deprecated. Look in docs and apply fix suggested.
    • Homepage will now load.
  • un-disableKinds other Kinds, no errors.
  • Site now does not break on 0.65.3.

You probably have other things you will want to fix:

12

@pointyfar Thanks for this speedy response. I did try switching to “_index.md” as well as a couple other tweaks suggested by @bep (see above). They helped, but there was still one massive hangup:

Internal Markdown links worked in 0.16, but gave 404’s with 0.18 and later hugo versions. The breakage occurred about three years ago, and we never received a clear answer for a solution. So we stayed on 0.16.

I recently put a question to the forum (#9 above) asking about how relative links work today in Markdown but again did not receive a clear answer or link to documentation that I could rely on. I am reluctant to guess how hugo creates the links via experimentation, and then hope the process remains the same in future versions - we already got burned once.

Now that we can rebuild and use 0.16, it’s still not obvious that it would be worth the effort to tweak the format of the (2,000) links across all our files. But if there is a straightforward solution (especially for handling our current Markdown link variations shown in #5 above without change) it would be great to see that documented. Thanks again.

13

Have a look at the new render hooks: https://gohugo.io/getting-started/configuration-markup#markdown-render-hooks