docs: use different docs theme, update docs and examples, and improve docs build

.pre-commit-config.yaml

@@ -7,6 +7,12 @@ repos:
     hooks:
     -   id: trailing-whitespace
     -   id: check-yaml
+        name: check-yaml for mkdocs.yml
+        files: ^mkdocs\.yml$
+        args: [--unsafe]
+    -   id: check-yaml
+        name: check-yaml for other YAML files
+        exclude: ^mkdocs\.yml$
     -   id: check-added-large-files
 -   repo: https://github.com/psf/black
     rev: 24.10.0