Hugo docs: Support newer Hugo and Hugo Relearn versions; update README

[bernhardkaindl]

Update Hugo version support to work with the current Hugo version

Follow-up PR: #6267

This PR fixes using the Ubuntu snap to render the Hugo docs.

Changes:

• Hugo Relearn 6.x uses the linkTitle front matter option now:
  Quote from the release notes: The front matter option menuTitle deprecated in 5.24.0 was removed in favor for Hugo’s own linkTitle.
• Newer versions of Hugo require the option unsafe = true to include raw HTML.
• Two Hugo Relearn 6.x partials need fixes for newer versions of Hugo.

Update doc/README.md accordingly

• Update the information on supported versions.
• Add information on the breaking changes in Hugo Relearn 7.x.x to watch out for.
• While at it, fix/improve the formatting of doc/README.md:
  • Spelling fixes/improvements
  • Fix markdown linting errors (empty lines for spacing, no bare links)
    • Tidy up the document structure

[lindig]

I'm not familiar with the details of Hugo but this looks reasonable to me.

[robhoes]

Is this intentional?

[bernhardkaindl]

Yes. It is only an intermediate step in making progress with a small PR.

We could go to Relearn 7 directly on one hop, but then the PR would be far more extensive.
In this case, this intermediate line would not show up in the final change, it would
be reverted to the official Relearn 7 repo in the second part of that future PR.
However, that cumulative PR would be more significant than two smaller step-by-step PRs.

A fuller explanation

This is only a good intermediary step before the next update which then could upgrade the Relearn theme to the current version of Relearn.

I asked Sören Weber (https://github.com/McShelby, the author of Relearn) if he could help. He responded, "The file structure of your repo is uncommon." and linked to one hint. This also suggests that some changes to the structure of the partials might be needed for Relearn 7.

I meanwhile researched the compatibility with upstream Relearn 7 further

According to this, the final update to the current Relearn 7 will need a small structural change as Relearn 7 does not support the architecture of how XenAPI classes and releases are typed, and it suggests that content-generating code should be moved to the content.html partial as documented in the Relearn documentation at https://mcshelby.github.io/hugo-theme-relearn/configuration/customization/partials/index.html

Using this guidance, I've found a working solution for those issues, which, instead of special types for XenAPI classes and releases, which need to be maintained and can no longer include the header.html and footer.html (those don't exist in Relearn 7).

Instead, the code in the classes and releases partials should be merged into a content.html template to generate that content. I have a proof-of-concept: It updates the nearly empty class and release files (140 files) and merged the content generation into a new content.html partial according to the Hugo documentation.

But let's return to this PR, which is just a relatively small second intermediary step:

I solved the issues taken initially during the review by changing the URL of the Relearn module to a fork of Relearn that we can use without having to copy partials from Relearn (like I initially had):

Here are the details

For the details of the issue fixed in the PR and the full update to Relearn 7,
I asked Sören Weber (the author of Relearn) in McShelby/hugo-theme-relearn#1004 if he has some guidance on how to resolve the issue at hand.
He linked to https://mcshelby.github.io/hugo-theme-relearn/configuration/customization/designs/index.html#migration-to-relearn-7-or-higher.
Here is his answer: McShelby/hugo-theme-relearn#1004 (comment)

This solution goes in this direction: It compromises between ease of use (in this case, support for using the Ubuntu snap package and any new build of Hugo in general) and using a moderately new version (or, in this case, fork) of Relearn with the needed fixes.

Conclusion

After solving the compatibility issue and updating Relearn 7.x as described in the README.md, the upstream version will again be used. This is only an intermediate deviation from upstream to facilitate the upgrade.

Alternative

Not making this change would require installing a specific older version (possibly from the source) to generate the docs. This small change is more manageable than installing a special older version of Hugo for development and maintenance until all upgrade problems are fully solved.

[bernhardkaindl]

Followed up by #6267