doc: replace large image files with external URLs

[trueNAHO]

Replace large image files in the repository with external URLs to reduce
repository size and encourage future large assets to be added
externally.

The images were uploaded to GitHub with its drag-and-drop functionality.

Although the images can no longer be viewed offline, this is a
worthwhile trade-off given the rarity of this use-case.

[danth]

Mixed opinions on this:

• Keeping the images in the repository might be useful for doc: install Stylix documentation as manpage  #635 or similar: for example NixOS has an option to install the HTML manual locally.
• Removing them makes it more likely for the links to break in the future, if the repository is moved from GitHub to another service, or in archival programs such as Arctic Code Vault.
• The files will be retained in the Git history, so doing a full clone will still need to download them.
• On the other hand, this will reduce bandwidth by a couple of megabytes for the average user fetching the repository as a flake input.

[danth]

As a workaround to keep support for viewing documentation offline, we could fetch the images here using fetchurl and copy them into the package. This would also require patching the Markdown files to reference the local image.

• This requires more maintenance effort.
• This still relies on the GitHub links being accessible, at least at build time.

[trueNAHO]

My main concern with keeping these "non-essential" documentation assets in the repository makes it very tempting to override them when updating them. In the future for example, this would cause the Git repo to be 100MB large with over 90% attributed to non-essential visualizations, where we essentially never care about anything other than the latest version of the visualizations, unlike the source code where history is valuable.

Working with such a bloated Git repo would be rather annoying. The fact that the .tar.gz is smaller is merely a side-effect.

For reference, I have thought about implementing something in the future where demonstrations could be automatically generated, which would keep the documentation in sync with the functionality and this could be used in PRs and issues to find color inconsistencies. In that case, somewhat frequent changes to these visualizations would merely bloat the repository size.

[danth]

I have thought about implementing something in the future where demonstrations could be automatically generated

Same - just automatically screenshot the testbeds once the target is fully loaded. The NixOS testing framework already has the functionality for this.

In this case the screenshots could just be dependencies of the docs derivation, and built when required.

However it would only show the initial page, which in some cases is not as interesting as a page further into the interaction. For example, the initial page of VSCode is not as interesting as having a file open. Also, we would have to maintain code to detect when the target is fully loaded.