From 4596e27eb017cef48140666b6f560c7dcbb333b9 Mon Sep 17 00:00:00 2001
From: Joachim Wiberg <troglobit@gmail.com>
Date: Thu, 30 Jul 2026 12:00:57 +0200
Subject: [PATCH] doc: simplify and add some polish to the User Guide

Both the Finit project and Infix use the same MkDocs Material setup, and
in the latter the User Guide has picked up a lot of polish that never
made it back here: a single sidebar with section indexes instead of
tabs, footnote tooltips, more pymdownx markup, image zoom tuning, and no
generator advert in the footer.

Signed-off-by: Joachim Wiberg <troglobit@gmail.com>
---
 mkdocs.yml | 107 ++++++++++++++++++++++++++++++++++-------------------
 1 file changed, 68 insertions(+), 39 deletions(-)

diff --git a/mkdocs.yml b/mkdocs.yml
index 8d02f735..0a8b362c 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -1,9 +1,9 @@
-site_name: ""
+site_name: User's Guide
 site_description: Fast Init for Linux Systems
 site_url: http://finit-project.github.io
 repo_url: https://github.com/finit-project/finit
 repo_name: Finit Project
-copyright: Copyright &copy; 2008-2025 Joachim Wiberg
+copyright: Copyright &copy; 2008-2026 Joachim Wiberg
 docs_dir: doc/
 edit_uri: edit/master/doc/
 extra_css:
@@ -13,42 +13,6 @@ exclude_docs: |
   TODO.md
   ChangeLog.md
 
-theme:
-  logo: img/logo.png
-  name: material
-  features:
-    - toc.follow
-    - toc.integrate
-    - navigation.path
-    - navigation.instant
-    - navigation.instant.progress
-    - navigation.tracking
-    - navigation.tabs
-#    - navigation.sections
-#    - navigation.expand
-#    - navigation.top
-    - navigation.footer
-    - search.highlight
-    - search.share
-#    - content.action.edit
-    - content.code.copy
-    - content.code.annotate
-  palette:
-    - media: "(prefers-color-scheme: light)"
-      scheme: default
-      primary: orange
-      accent: orange
-      toggle:
-        icon: material/weather-night
-        name: Switch to dark mode
-    - media: "(prefers-color-scheme: dark)"
-      scheme: slate
-      primary: black
-      accent: black
-      toggle:
-        icon: material/weather-sunny
-        name: Switch to light mode
-
 nav:
   - Getting Started:
     - Introduction: index.md
@@ -94,14 +58,62 @@ nav:
     - Distributions: distro.md
     - Requirements: requirements.md
 
+theme:
+  logo: img/logo.png
+  name: material
+  features:
+    - toc.follow
+#    - toc.integrate
+    - navigation.path
+    - navigation.instant
+    - navigation.instant.progress
+    - navigation.tracking
+    - navigation.indexes
+#    - navigation.tabs
+#    - navigation.sections
+#    - navigation.expand
+#    - navigation.top
+#    - navigation.footer
+    - search.highlight
+    - search.share
+#    - content.action.edit
+    - content.code.copy
+    - content.code.annotate
+    - content.footnote.tooltips
+  palette:
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: orange
+      accent: orange
+      toggle:
+        icon: material/weather-night
+        name: Switch to dark mode
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: black
+      accent: black
+      toggle:
+        icon: material/weather-sunny
+        name: Switch to light mode
+
 markdown_extensions:
   - admonition
   - attr_list
+  - footnotes
+  - pymdownx.blocks.caption
+  - pymdownx.critic
+  - pymdownx.caret
+  - pymdownx.keys
+  - pymdownx.mark
+  - pymdownx.tilde
   - pymdownx.details
   - pymdownx.superfences
   - pymdownx.highlight:
       anchor_linenums: true
   - pymdownx.inlinehilite
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
   - pymdownx.snippets
   - pymdownx.tabbed:
       alternate_style: true
@@ -112,9 +124,26 @@ markdown_extensions:
 plugins:
   - search
   - callouts
-  - glightbox
+  - glightbox:
+      touchNavigation: true
+      loop: false
+      effect: zoom
+      slide_effect: slide
+      width: 100%
+      height: auto
+      zoomable: true
+      draggable: true
+      skip_classes:
+        - custom-skip-class-name
+      auto_themed: true
+      auto_caption: false
+      caption_position: bottom
+      background: black
+      shadow: false
+      manual: false
 
 extra:
+  generator: false
   homepage: https://finit-project.github.io/
   social:
     - icon: fontawesome/brands/github