docs: Update docs/README.md and Hugo Relearn to 5.23.0 (#6251)

Minor updates of the Hugo documentation:

- The current Ubuntu `snap` package of Hugo is not supported by the
docs.
  We should take a first minor step towards fixing this.

-
[`doc/README.md`](https://github.com/xapi-project/xen-api/blob/master/doc/README.md)
is outdated and should be updated ([new
version](https://github.com/xenserver-next/xen-api/blob/docs-update-README-and-hugo-relearn-to-5.23/doc/README.md)).
  It says that the Ubuntu snap of Hugo works, but it does not anymore.
  Fix this by updating the outdated information.

- An initial fix is to update the Relearn theme from 5.20.x to 5.23.0:
  - It does not introduce breaking changes.
- It introduces more straightforward page links and deprecates older
syntax.
  - Fix the warnings by updating relative links accordingly.

A preview is available on my site:
https://xenserver-next.github.io/xen-api/index.html

doc/README.md

@@ -1,9 +1,51 @@
-Quick start guide:
+# Quick start guide:
 
 - Visit https://xapi-project.github.io/new-docs/ to view the current documentation.
+
+## Required software
+
+The docs use Hugo and the [Hugo Relearn theme](https://mcshelby.github.io/hugo-theme-relearn),
+an enhanced fork of the popular Hugo Learn theme.
+
+### Compatible versions
+
+Due to a number of gradual changes in Hugo and Relearn,
+the docs are currently only compatible with specific older versions of Hugo and Relearn.
+
+Hugo v0.121.0 to ~v0.127.0 (the current version of the Ubuntu `snap` is too recent)
+- Fixes to support newer versions are forthcoming.
+
+Hugo Relearn 5.24.0 (defined by a git tag in doc/go.mod)
+- Note: Hugo Relearn >= 5.25 currently trigger additional warnings due to deprecations.
+- Further updates fix this situation are forthcoming step by step.
+
+Hugo Relearn >= 5.24.0 and < 6.x are expected to work:
+- https://mcshelby.github.io/hugo-theme-relearn/introduction/releasenotes/5/index.html#5-24-0
+- Breaking changes in Relearn 6.0.0:
+  https://mcshelby.github.io/hugo-theme-relearn/introduction/releasenotes/6/#6-0-0
+
+## Installation
+
 - Install Hugo; follow the guidance on https://gohugo.io/getting-started/installing.
-  You'll need Go as well: see https://go.dev/
-  - On Ubuntu 22.04 and older, use `sudo snap install hugo` to get the needed newer version of `hugo`.
+  You'll need to install Go as well: see https://go.dev/
+  - Hugo installation is described at https://gohugo.io/installation
+  - On Ubuntu 24.04, the version installed by `apt` works.
+  - On Ubuntu 22.04 and older:
+    - `apt-get install hugo` would install a version that is too old.
+    - `sudo snap install hugo` installs a too recent version
+
+  - To install Hugo from source, you need a recent `golang-1.2x` compiler:
+    - On Ubuntu 22.04, this can be done with:
+      ```bash
+      sudo apt install golang-1.23-go
+      # Add it to your path, assuming your .local/bin/ is early in your PATH:
+      ln -s /usr/lib/go-1.23/bin/go ~/.local/bin/go
+      go version
+      go install github.com/gohugoio/[email protected]
+      ```
+
+## Development
+
 - Run a local server: `hugo server`
 - Open a browser at http://127.0.0.1:1313/new-docs/
 - Add content to `doc/content/`:

doc/content/design/cpu-levelling-v2.md

@@ -29,7 +29,7 @@ The old XS 5.6-style Heterogeneous Pool feature that is based around hardware-le
 History
 =======
 
-- Original XS 5.6 design: [heterogeneous-pools](../heterogeneous-pools)
+- Original XS 5.6 design: [heterogeneous-pools](heterogeneous-pools)
 - Changes made in XS 5.6 FP1 for the DR feature (added CPUID checks upon migration)
 - XS 6.1: migration checks extended for cross-pool scenario
 

doc/content/design/local-database.md

@@ -25,7 +25,7 @@ We propose to:
   this should reduce the number of RPCs across the network.
 
 In a later phase we can move to a completely
-[distributed database](../distributed-database).
+[distributed database](distributed-database/index).
 
 Replicating the database
 ------------------------

doc/content/design/multiple-cluster-managers.md

@@ -14,7 +14,7 @@ revision_history:
 Introduction
 ------------
 
-Xapi currently uses a cluster manager called [xhad](../../features/HA/HA.html). Sometimes other software comes with its own built-in way of managing clusters, which would clash with xhad (example: xhad could choose to fence node 'a' while the other system could fence node 'b' resulting in a total failure). To integrate xapi with this other software we have 2 choices:
+Xapi currently uses a cluster manager called [xhad](../toolstack/features/HA/index). Sometimes other software comes with its own built-in way of managing clusters, which would clash with xhad (example: xhad could choose to fence node 'a' while the other system could fence node 'b' resulting in a total failure). To integrate xapi with this other software we have 2 choices:
 
 1. modify the other software to take membership information from xapi; or
 2. modify xapi to take membership information from this other software.
@@ -70,4 +70,4 @@ The `xapi.conf` file will have a new field: `cluster-stack-root` which will have
 
 In `Pool.enable_ha` with `cluster_stack="foo"` we will verify that the subdirectory `<cluster-stack-root>/foo` exists. If it does not exist, then the call will fail with `UNKNOWN_CLUSTER_STACK`.
 
-Alternative cluster stacks will need to conform to the exact same interface as [xhad](../../features/HA/HA.html).
+Alternative cluster stacks will need to conform to the exact same interface as [xhad](../toolstack/features/HA).

doc/content/design/ocfs2/index.md

@@ -461,7 +461,7 @@ Summary of the impact on the admin
 
 OCFS2 is fundamentally a different type of storage to all existing storage
 types supported by xapi. OCFS2 relies upon O2CB, which provides
-[Host-level High Availability](../../../features/HA/HA.html). All HA implementations
+[Host-level High Availability](../../toolstack/features/HA/index). All HA implementations
 (including O2CB and `xhad`) impose restrictions on the server admin to
 prevent unnecessary host "fencing" (i.e. crashing). Once we have OCFS2 as
 a feature, we will have to live with these restrictions which previously only

doc/content/toolstack/features/DR/index.md

@@ -2,7 +2,7 @@
 title = "Disaster Recovery"
 +++
 
-The [HA](../HA/HA.html) feature will restart VMs after hosts have failed, but what
+The [HA](HA) feature will restart VMs after hosts have failed, but what
 happens if a whole site (e.g. datacenter) is lost? A disaster recovery
 configuration is shown in the following diagram:
 

doc/content/toolstack/features/snapshots/index.md

@@ -8,7 +8,7 @@ Snapshots represent the state of a VM, or a disk (VDI) at a point in time. They
 - experiments (take snapshot, try something, revert back again)
 - golden images (install OS, get it just right, clone it 1000s of times)
 
-Read more about [the Snapshot APIs](../../xen-api/snapshots.html).
+Read more about [the Snapshot APIs](../../../xen-api/topics/snapshots).
 
 Disk snapshots
 ==============

doc/content/xapi/cli/_index.md

@@ -179,5 +179,5 @@ Yet other commands do not actually do any XenAPI calls, but instead get "helpful
 
 The following tutorials show how to extend the CLI (and XenAPI):
 
--   [Adding a field]({{< relref "../guides/howtos/add-field.md" >}})
--   [Adding an operation]({{< relref "../guides/howtos/add-function.md" >}})
+-   [Adding a field](../guides/howtos/add-field)
+-   [Adding a function](../guides/howtos/add-function)

doc/content/xapi/guides/howtos/add-class.md

@@ -6,8 +6,8 @@ This document describes how to add a new class to the data model that
 defines the Xen Server API. It complements two other documents that
 describe how to extend an existing class:
 
-* [Adding a Field]({{< ref add-field.md >}})
-* [Adding a Function]({{< ref add-function.md >}})
+* [Adding a field](add-field)
+* [Adding a function](add-function)
 
 As a running example, we will use the addition of a class that is part
 of the design for the PVS Direct feature. PVS Direct introduces

doc/content/xen-api/topics/snapshots.md

@@ -11,7 +11,7 @@ They can be used for:
 - experiments (take snapshot, try something, revert back again)
 - golden images (install OS, get it just right, clone it 1000s of times)
 
-Read more about [Snapshots: the High-Level Feature](../features/snapshots/snapshots.html).
+Read more about [Snapshots: the High-Level Feature](../../toolstack/features/snapshots/index).
 
 Taking a VDI snapshot
 =====================

doc/content/xenopsd/architecture/_index.md

@@ -17,7 +17,7 @@ Managing a VM means:
 - providing updates to clients when things change (reboots, console becomes
   available, guest agent says something etc).
 
-For a full list of features, consult the [features list](features.html).
+For a full list of features, consult the [feature list](../features).
 
 Each Xenopsd instance has a unique name on the host. A typical name is
 

doc/go.mod

@@ -2,4 +2,4 @@ module xapi-project.github.io
 
 go 1.20
 
-require github.com/McShelby/hugo-theme-relearn v0.0.0-20230905210935-196188b7f3bd // indirect
+require github.com/McShelby/hugo-theme-relearn v0.0.0-20231029175538-7ae1435626d7 // indirect