docs(config): Tidy up and better document mkdocs.yml

docs/mkdocs.yml

@@ -1,12 +1,28 @@
+# Site specific:
 site_name: 'Docker Mailserver'
 site_description: 'A fullstack but simple mail server (SMTP, IMAP, LDAP, Antispam, Antivirus, etc.) using Docker.'
 site_author: 'docker-mailserver (Github Organization)'
+copyright: '<p>&copy <a href="https://github.com/docker-mailserver"><em>Docker Mailserver Organization</em></a><br/><span>This project is licensed under the MIT license.</span></p>'
+
+# Project source specific:
 repo_name: 'docker-mailserver'
 repo_url: 'https://github.com/docker-mailserver/docker-mailserver'
-copyright: '<p>&copy <a href="https://github.com/docker-mailserver"><em>Docker Mailserver Organization</em></a><br/><span>This project is licensed under the MIT license.</span></p>'
+
+# All docs `edit` button will go to this subpath of the `repo_url`:
+# For versioned docs, this may be a little misleading for a user not viewing the `edge` docs which match the `master` branch.
 edit_uri: 'edit/master/docs/content'
+
+# The main docs content lives here, any files will be copied over to the deployed version,
+# unless the file or directory name is prefixed with a `.`
 docs_dir: 'content/'
-site_url: 'https://docker-mailserver.github.io/docker-mailserver'
+
+# Canonical URL (HTML content instructs search engines that this is where the preferred version of the docs is located, useful when we have duplicate content like versioned docs)
+# https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/Choosing_between_www_and_non-www_URLs#using_%3Clink_relcanonical%3E
+# Also required for `sitemap.xml` generation at build time; which bots use to assist them crawling and indexing a website,
+# the `mkdocs-material` 'Instant Navigation' feature utilizes the sitemap data to work.
+site_url: 'https://docker-mailserver.github.io/docker-mailserver/edge'
+
+# Anything related to the `mkdocs-material` theme config goes here:
 theme:
   name: 'material'
   favicon: assets/logo/favicon-32x32.png
@@ -18,6 +34,7 @@ theme:
     - navigation.expand
     - navigation.instant
 
+# We make some minor style adjustments or resolve issues that upstream `mkdocs-material` would not accept a PR for:
 extra_css:
   - assets/css/customizations.css
 
@@ -28,6 +45,7 @@ extra:
   version:
     provider: mike
 
+# Various extensions for `mkdocs` are enabled and configured here to extend supported markdown syntax/features.
 markdown_extensions:
   - toc:
       anchorlink: true
@@ -35,6 +53,11 @@ markdown_extensions:
   - attr_list
   - admonition
   - pymdownx.details
+  - pymdownx.superfences
+  - pymdownx.magiclink
+  - pymdownx.emoji:
+      emoji_index: !!python/name:materialx.emoji.twemoji
+      emoji_generator: !!python/name:materialx.emoji.to_svg
   - pymdownx.highlight:
       extend_pygments_lang:
         - name: yml
@@ -53,12 +76,12 @@ markdown_extensions:
           lang: txt
         - name: caddyfile
           lang: txt
-  - pymdownx.superfences
-  - pymdownx.magiclink
-  - pymdownx.emoji:
-      emoji_index: !!python/name:materialx.emoji.twemoji
-      emoji_generator: !!python/name:materialx.emoji.to_svg
 
+# Hard-coded navigation list. Key(UI label): Value(relative filepath from `docs_dir`).
+# - If referencing a file more than once, the URLs will all point to the nav hierarchy of the last file reference entry. That usually breaks UX, try avoid it.
+# - The top-level elements are presented as tabs (due to `theme.features.navigation.tabs`).
+#   - Nested elements appear in the sidebar (left) of each tabs page.
+#   - 3rd level and beyond are automatically expanded in the sidebar instead of collapsed (due to `theme.features.navigation.expand`)
 nav:
   - 'Home': index.md
   - 'Introduction': introduction.md