From 34173e8d6b18126ff12adf564afaf392932696ec Mon Sep 17 00:00:00 2001
From: polarathene <5098581+polarathene@users.noreply.github.com>
Date: Sun, 10 Mar 2024 21:24:36 +1300
Subject: [PATCH] docs: Introduce `TaskList` for pro/con lists

Bullet points aren't that nice when we're differentiating with an icon already, but `mkdocs-material` makes it difficult to target via CSS as we cannot easily add a list to a `ul` element and it'd be a bit awkward to append to each list item.

Task list feature works well, but customizing the unchecked style would look better. This is acceptable since we're not a TaskList anywhere else.
---
 docs/content/assets/css/customizations.css | 34 ++++++++++++++++++++++
 docs/content/config/advanced/kubernetes.md | 10 +++----
 docs/mkdocs.yml                            |  2 ++
 3 files changed, 41 insertions(+), 5 deletions(-)

diff --git a/docs/content/assets/css/customizations.css b/docs/content/assets/css/customizations.css
index 25cb0274..7255a837 100644
--- a/docs/content/assets/css/customizations.css
+++ b/docs/content/assets/css/customizations.css
@@ -107,3 +107,37 @@ div.md-content article.md-content__inner a.toclink code {
 .md-nav__item--nested > .md-nav__link {
   font-weight: 700;
 }
+
+/* ============================================================================================================= */
+
+/*
+  TaskList style for a pro/con list. Presently only used for this type of list in the kubernetes docs.
+  Uses a custom icon for the unchecked (con) state: :octicons-x-circle-fill-24:
+  https://github.com/squidfunk/mkdocs-material/discussions/6811#discussioncomment-8700795
+
+  TODO: Can better scope the style under a class name when migrating to block extension syntax:
+  https://github.com/facelessuser/pymdown-extensions/discussions/1973
+*/
+
+:root {
+  --md-tasklist-icon--failed: url('data:image/svg+xml;charset=utf-8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M1 12C1 5.925 5.925 1 12 1s11 4.925 11 11-4.925 11-11 11S1 18.075 1 12Zm8.036-4.024a.751.751 0 0 0-1.042.018.751.751 0 0 0-.018 1.042L10.939 12l-2.963 2.963a.749.749 0 0 0 .326 1.275.749.749 0 0 0 .734-.215L12 13.06l2.963 2.964a.75.75 0 0 0 1.061-1.06L13.061 12l2.963-2.964a.749.749 0 0 0-.326-1.275.749.749 0 0 0-.734.215L12 10.939Z"/></svg>');
+}
+
+.md-typeset [type="checkbox"] + .task-list-indicator::before {
+  background-color: rgb(216, 87, 48);
+  -webkit-mask-image: var(--md-tasklist-icon--failed);
+  mask-image: var(--md-tasklist-icon--failed);
+}
+
+/* More suitable shade of green */
+.md-typeset [type=checkbox]:checked+.task-list-indicator:before {
+  background-color: rgb(97, 216, 42);
+}
+
+/* Tiny layout shift */
+[dir=ltr] .md-typeset .task-list-indicator:before {
+  left: -1.6em;
+  top: 1px;
+}
+
+/* ============================================================================================================= */
diff --git a/docs/content/config/advanced/kubernetes.md b/docs/content/config/advanced/kubernetes.md
index d2960fe8..62308750 100644
--- a/docs/content/config/advanced/kubernetes.md
+++ b/docs/content/config/advanced/kubernetes.md
@@ -524,14 +524,14 @@ The major problem with exposing DMS to the outside world in Kubernetes is to [pr
 
     !!! abstract "Advantages / Disadvantages"
 
-        - :heavy_check_mark: Preserves the origin IP address of clients (_which is crucial for DNS related checks_);
-        - :heavy_check_mark: Aligns with a best practice for Kubernetes by using a dedicated ingress, routing external traffic to the k8s cluster (_with the benefits of flexible routing rules_)
-        - :heavy_check_mark: Avoids the restraint of a single [node][Kubernetes-nodes] (_as a workaround to preserve the original client IP_).
-        - :heavy_multiplication_x: Introduces complexity by requiring:
+        - [x] Preserves the origin IP address of clients (_which is crucial for DNS related checks_);
+        - [x] Aligns with a best practice for Kubernetes by using a dedicated ingress, routing external traffic to the k8s cluster (_with the benefits of flexible routing rules_)
+        - [x] Avoids the restraint of a single [node][Kubernetes-nodes] (_as a workaround to preserve the original client IP_).
+        - [ ] Introduces complexity by requiring:
             - A reverse-proxy / ingress controller (_potentially extra setup_)
             - Kubernetes manifest changes for the DMS configured `Service`
             - DMS configuration changes for Postfix and Dovecot
-        - :heavy_multiplication_x: To keep support for direct connections to DMS services internally within cluster, service ports must be "duplicated" to offer an alternative port for connections using PROXY protocol.
+        - [ ] To keep support for direct connections to DMS services internally within cluster, service ports must be "duplicated" to offer an alternative port for connections using PROXY protocol.
 
     **Examples**
 
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
index 84366423..8dd192ca 100644
--- a/docs/mkdocs.yml
+++ b/docs/mkdocs.yml
@@ -82,6 +82,8 @@ markdown_extensions:
           format: !!python/name:pymdownx.superfences.fence_code_format
   - pymdownx.tabbed:
       alternate_style: true
+  - pymdownx.tasklist:
+      custom_checkbox: true
   - pymdownx.magiclink
   - pymdownx.inlinehilite
   - pymdownx.tilde