From bbaca9a468f0a614011be2038b3ed754d6f30c9d Mon Sep 17 00:00:00 2001
From: polarathene <5098581+polarathene@users.noreply.github.com>
Date: Wed, 10 Mar 2021 17:30:57 +1300
Subject: [PATCH] docs(config): Tidy up and better document `mkdocs.yml`
---
docs/mkdocs.yml | 37 ++++++++++++++++++++++++++++++-------
1 file changed, 30 insertions(+), 7 deletions(-)
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index 49f10003..efea8172 100644
--- a/docs/mkdocs.yml
+++ b/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: '© Docker Mailserver Organization
This project is licensed under the MIT license.
'
+
+# Project source specific:
repo_name: 'docker-mailserver'
repo_url: 'https://github.com/docker-mailserver/docker-mailserver'
-copyright: '© Docker Mailserver Organization
This project is licensed under the MIT license.
'
+
+# 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