Add dark mode theme for main document configurable by button

[sadielbartholomew]

See issue #607 for discussion of these changes.

Note:

• this PR is a proof of concept for that Issue that doesn't add dark mode everywhere, only for the build of the draft main document - but it can be used as a basis to add dark mode functionality to other documents (the website might need a different approach to support dark mode, since it is built through GitHub Pages I believe and uses Bootstrap components where Bootstrap likely supports dark mode more natively);
• to create a preview, I had to copy the built HTML up one directory to the repo root on my fork's branch, meaning one extra commit here - which, after passing review, can be revoked (so ignore the line count which is mostly from that commit's addition of the duplicate file).

PR/Review Notes

I have built this branch to my local fork GitHub Pages, so the document under this branch can be viewed at: https://sadielbartholomew.github.io/cf-conventions/cf-conventions-previewonly.html

But for a quick view, here is a screenshot of the implemented 'dark mode', noting the button at top right which whn pressed switches between the dark and light mode and by default takes that expressed as preference by the user's browser settings:

As for design decisions:

• I chose a colour palette for dark mode based on the palette of light mode from the AsciiDoc default: traditional blues for links, reds for headings and captions, but in a dark/light inverse way to reflect light -> dark mode.
• Top right was chosen to position the toggle button since the top means a viewer won't miss the button, but having it top left would be too distracting I think because we start reading each line from the left.

I checked the whole document to ensure it is readable in dark mode. The only difficulty are the images - but most are still readable, whether defined with a transparent background e.g:

or with a fixed white background, which is less pretty and keeps the images in light mode, but fine for readability:

The only outstanding issue to resolve for a dark mode are the tables 9.2, 9.3, 9.4, 9.5 (9.2 - 9.5) which are colour-coded to convey meaning with the background colour of each cell. Those colours are designed for dark text to be readable and with light text, become hard to read if not unreadable:

However, since figure and table colours are already being re-valuated for #404, and until then the viewer can easily toggle back to light mode to view these in a readble way, I don't think it is a blocker for the dark mode of this PR to be ready-to-use and therefore this branch to be merged. But it depends what others think.

Release checklist

n/a for both:

• history.adoc up to date?
• Conformance document up to date?

For maintainers

After the merge remember to delete the source branch.
Tags are set at the conclusion of the annual meeting; until then, main always is a draft for the next version.

[sadielbartholomew]

(Just adding some commits aiming to force GitHub Pages to produce a preview from my local branch - not trivial since the built HTML gets put under build/ so I need to build via CI to avoid moving the build document upwards in the directory structure.)

[sadielbartholomew]

(Going to have to leave this until next working week - so no preview webpage for now 😢 but I will add one on Monday.)

[sadielbartholomew]

Preview now available from a GitHub Pages fork on my build at: https://sadielbartholomew.github.io/cf-conventions/cf-conventions-previewonly.html. Unfortunately I couldn't find another way to build without adding at least one commit to this branch (you can't preview HTML from under a directory that isn't root or 'docs/' in GitHub Pages and I did try with GitHub Actions workflows to get a deploy/publish workflow but I gave up after a few hours of fighting various errors given I knew I could just move the built HTML one directory up to get a working preview, though it requires a new commit here...)