docs(deps): bump mkdocs-material to new major version 8

[wernerfred]

Description

bump mkdocs-material to 8.0.2

Todos:

• We should carefully investigate the preview if something broke (e.g. regarding seealso removal)
• We should investigate new features and if we want them and how to enable (e.g. version warning)

Main changes:

• Added support for code annotations
• Added support for anchor tracking
• Added support for version warning
• Added copyright partial for easier override
• Removed deprecated content tabs legacy implementation
• Removed deprecated seealso admonition type
• Removed deprecated site_keywords setting (unsupported by MkDocs)
• Removed deprecated prebuilt search index support
• Removed deprecated web app manifest – use customization
• Removed extracopyright variable – use new copyright partial
• Removed Disqus integation – use customization
• Switched to :is() selectors for simple selector lists
• Switched autoprefixer from last 4 years to last 2 years
• Improved CSS overall to match modern standards
• Improved CSS variable semantics for fonts
• Improved extensibility by restructuring partials
• Improved handling of details when printing
• Improved keyboard navigation for footnotes

Type of change

• Improvement (non-breaking change that does improve existing functionality)

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation (README.md or the documentation under docs/)
• If necessary I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes

[polarathene]

We should carefully investigate the preview if something broke (e.g. regarding seealso removal)

I believe we already handled seealso when it was deprecated, a quick grep for it in the docs should clarify that.

As for checking if a preview broke in an automated way, there are some tools/services for webpage diffs, they might be useful or sometimes just noise. We may qualify for the free or open-source tiers of some services that we could integrate the CI with, at least for PRs that bump the mkdocs container version.. I don't have spare time to allocate to such unfortunately.

We should investigate new features and if we want them and how to enable (e.g. version warning)

That would be good too. I'm hoping to have some time to push my contributors doc page that was left WIP early in the year, that covered a bunch of features with examples to show how we could leverage them in our docs. Probably been some additions since that need to be added too 😅 I should be able to get that sorted out later this month or early Jan.

[wernerfred]

@polarathene can you have a look at https://squidfunk.github.io/mkdocs-material/setup/setting-up-versioning/#version-warning

I'm not sure if i implemented this correctly in 9d35f1e by setting the version to edge bc looking at https://github.com/docker-mailserver/docker-mailserver/blob/gh-pages/versions.json we have no alias set on the versions

EDIT: Seems like i broke it anyways with 1d44ad9

[georglauterbach]

I'd not add the version warning. We actually encourage users to pick the right version they're running, not just using :edge. This warning may (well, I think it is) be misleading.

PS: Will share some more feedback later. Going to sleep now.

[georglauterbach]

I'd add navigation.tracking to the theme features and content.code.annotate so we can annotate code now :D As I said, I'd not go with the "go to the latest docs" feature.

[georglauterbach]

I added the code annotation syntax. I'm fine with this PR then :D

[polarathene]

We actually encourage users to pick the right version they're running, not just using :edge. This warning may (well, I think it is) be misleading.

Isn't that the purpose of this feature too?

You may end up on the docs via link from a blog / guide about docker-mailserver, or an old issue or discussion via a search result (or possibly direct link from google search results, but I think I provided the information for Google to index edge).

I know that I've wound up on docs for certain projects via links that turned out to be the older releases, docs for rust crates / packages for example.

---

If you'd like to have it, but have trouble getting it working, for now perhaps just comment out the feature with a note about enabling it later (or separate PR/issue) if you don't want to block updating the image version 😅

I'd look into it myself but backlog is a bit busy elsewhere currently.

I'm not sure if i implemented this correctly in 9d35f1e by setting the version to edge bc looking at https://github.com/docker-mailserver/docker-mailserver/blob/gh-pages/versions.json we have no alias set on the versions

docker-mailserver/versions.json

Lines 2 to 6 in 2f14e13

	{
	"version": "edge",
	"title": "edge",
	"aliases": []
	},

Should be fine to add the default: latest alias value to the JSON directly on the gh-pages branch:

  {
    "version": "edge",
    "title": "edge",
-    "aliases": []
+    "aliases": [ "latest" ]
  },

Or adjust the latest value to edge or similar :)

[georglauterbach]

I'd still not add it. I think MkDocs makes a very good job at showing the version selector at the very top:)

@wernerfred If you think this PR is ready, just request me for review.

[github-actions]

Documentation preview for this PR is ready! 🎉

Built with commit: 36aefb7

[georglauterbach]

I just noticed my changes were overridden? Was there a reason for this? Either way, I'm very much fine with this :)

[wernerfred]

I just noticed my changes were overridden?

Maybe a caching issue? I only have one commit from your side (ignoring the master merges) and this one is still in place:
https://github.com/docker-mailserver/docker-mailserver/blame/36aefb75f75f025cd216d2731e29f0a158efe45d/docs/mkdocs.yml#L38

[georglauterbach]

I just noticed my changes were overridden?

Maybe a caching issue? I only have one commit from your side (ignoring the master merges) and this one is still in place: https://github.com/docker-mailserver/docker-mailserver/blame/36aefb75f75f025cd216d2731e29f0a158efe45d/docs/mkdocs.yml#L38

You're right: May GitHub app on my smartphone did cache to aggressively. Very good, all is well!