Document use of Hugo ref shortcode in README.md

We use the ref shortcode extensively to limit the risk of broken links
between pages on the website. Document this requirement in the README.

Promote the PDF generation section whilst here as it's also relevant to anyone
writing documentation.

Signed-off-by: Martyn Welch <martyn.welch@collabora.com>

README.md

@@ -31,6 +31,32 @@ layout guidelines:
   - Release notes
   - Release schedules
 
+## Use of Hugo `ref` shortcode
+
+Hugo provides the `ref` shortcode to aid with
+[creating links between documents](https://gohugo.io/content-management/cross-references/).
+This should be used for all references internal to the website. The generation
+process will fail when the target page of the reference can not be found,
+causing the CI to fail and thus aids with reducing the risk broken links being
+provided on the website.
+
+## Generating PDFs
+
+In order to generate PDFs, we are getting Hugo to create a simplified HTML
+pages. So as not to have every page generating a PDF, to get a page to be
+generated as a PDF (and html at the same time) add the following to the
+frontmatter of the page:
+
+```
+outputs = ["html", "pdf-in"]
+```
+
+This will result in the simplifed HTML being produced in a file called
+`index.pdf-in` in the relevant directory. The CI is configured to look
+for these files once Hugo has generated the site and create PDFs of them. For
+the page `www.apertis.org/concepts/foo/`, a PDF will be available as
+`www.apertis.org/concepts/foo/foo.pdf`.
+
 ## GitLab CI
 
 This project's static Pages are built by [GitLab CI][ci], following the steps
@@ -53,20 +79,3 @@ Read more at Hugo's [documentation][https://gohugo.io/overview/introduction/].
 If you clone or download this project to your local computer and run `hugo server`,
 your site can be accessed under `localhost:1313/hugo/`.
 
-## Generating PDFs
-
-In order to generate PDFs, we are getting Hugo to create a simplified HTML
-pages. So as not to have every page generating a PDF, to get a page to be
-generated as a PDF (and html at the same time) add the following to the
-frontmatter of the page:
-
-```
-outputs = ["html", "pdf-in"]
-```
-
-This will result in the simplifed HTML being produced in a file called
-`index.pdf-in` in the relevant directory. The kernel CI is configured to look
-for these files once Hugo has generated the site and create PDFs of them. For
-the page `www.apertis.org/concepts/foo/`, a PDF will be available as
-`www.apertis.org/concepts/foo/foo.pdf`.
-