Hugo docs: Enable dark mode support and PR review of Hugo doc updates on GH Pages of clone repos

[bernhardkaindl]

Hello @robhoes,

this PR submits two commits to the Hugo documentation site for review:

Commit 1:

• Hugo docs: Enable dark mode support and choosing the theme variant

  • You can test it on this site for review: https://xenserver-next.github.io/xen-api/

  Not needed for it but recommended, I think:

  • As https://mcshelby.github.io/hugo-theme-relearn/basics/requirements/index.html says that the latest version of https://mcshelby.github.io/hugo-theme-relearn/ needs Hugo 0.121.0, I suggest defining it as the minimum Hugo version in hugo.toml.
  • I also updated the version used for deployment to GitHub pages to the current version of Hugo (0.127.0)
  • Enabled the print icon for printing the site, see below.

Commit 2:

• Hugo docs: Support reviews of Hugo updates by publishing to a clone's gh-pages
  • This commit publishes the Hugo doc site for review to https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/, which is https://xenserver-next.github.io/xen-api/ for this PR.
  • This upload is only enabled for other site besides https://github.com/xapi-project/xen-api
    • The deployment to https://xapi-project.github.io/new-docs/ should not be influenced by this PR.

You can review the combined result of this PR at: https://xenserver-next.github.io/xen-api/

This is how it looks in e.g. https://github.com/xenserver-next/xen-api/actions/runs/9551625367:

With this, if the web browser or the OS specifies dark mode, the theme honors it.
In this configuration, it switches to the zen-dark variant of the theme by default, unless you switch to a fixed theme variant using the theme selector at the bottom of the left sidebar:

Except for a few minor dark mode theming issues from some graphics, the dark mode looks perfectly fine:

If dark mode is not selected by the OS or the browser, the auto theme switch continues to use the red theme variant, so no change in this case, except that you can now select a different theme variant if you want.

And I enabled the print support in Hugo for the home page and the section pages, so you can print the entire documentation site, which the case of the home page print, prints all pages, in which case, you get a printout of 273 pages PDF in A4. :)

[edwintorok]

Some doc pages were not written with dark mode in mind, e.g. https://xenserver-next.github.io/xen-api/toolstack/features/NUMA/index.html and https://xenserver-next.github.io/xen-api/toolstack/high-level/index.html, where you have an image with a white background.

There is an example on how to support that with a new figure-dynamic shortcode https://stenbrinke.nl/blog/adding-support-for-dark-and-light-images-to-hugo-figure-shortcode/ that supports specifying separate dark and light images.

[edwintorok]

Also not sure what happened to printing this part about vGPU but the colors are unreadable (it looks fine when not printing):

[contificate]

There is an example on how to support that with a new figure-dynamic shortcode https://stenbrinke.nl/blog/adding-support-for-dark-and-light-images-to-hugo-figure-shortcode/ that supports specifying separate dark and light images.

A much hackier way that doesn't involve recreating any diagrams is to filter: invert(1); any black-on-white images (works well in these very limited instances, but problematic generally). To be truly dynamic, future diagrams may wish to be only SVG (by using xournalpp or similar) - then, technically, we could dynamically change the colouring (some manual labour involved to make the SVGs amenable to this).

As for the printing, a workaround is to basically always disable "background graphics" from your browser's print options (I do this when printing websites generally, even without a dedicated print stylesheet). On the other end, if one is using a generic highlighter like hljs, it can make sense to just override all the styling in the print stylesheet.

I think these additions are nice, even if there's some stylistic hiccups to work against.

[robhoes]

I'm happy with the first commit, which adds some options to the docs site.

I'm not sure about the second one though. I don't like the idea of this automatic pushing back to my forked repo after creating a PR. If I want to show reviewers a preview of the docs site with my changes, I can push it myself to my gh-pages branch?

[bernhardkaindl]

Hi @robhoes, thanks for your comment!

I'd just like to answer or clarify what the second one does:

I'm not sure about the second one though. I don't like the idea of this automatic pushing back to my forked repo after creating a PR. If I want to show reviewers a preview of the docs site with my changes, I can push it myself to my gh-pages branch?

About "automatic pushing back to my forked repo after creating a PR"

Maybe this was not correctly communicated, because I forgot to describe how the deployment would work in this way:

It does not involve pushing to a gh-pages branch, but deploys using the GitHub action when the GitHub pages for the repository are changed to not deploy from the gh-pages branch but from the Actions workflow:

This way, this does not do a git push or any commit on your forked repo:

What it does:

• It uploads the static Hugo site as an artifact (which is not committed to git) to your repo or own space.
• It then publishes this artifact on our personal GitHub pages below the subdirectory /xen-api.

For this, I configured the pages of the forked repo at https://github.com//xen-api/settings/pages to switch the deployment source for GitHub actions from "Deploy from branch" (classic Pages using the gh-pages branch) to "GitHub Actions".

This picture should show how this is configured:

If you don't switch the configuration from the default "Deploy to a branch" to "GitHub Actions", the deployment should not actually go live on your personal GitHub pages.

I'm sorry that I forgot to mention and explain this configuration using this screenshot before!

Of course, I'm happy to submit the two commits separately to review them independent of each other!