chore(mkdocs): add some customizations, pymdown

Author: noelmcloughlin

template/docs/js/extra-loader.js

@@ -0,0 +1,3 @@
+// See https://facelessuser.github.io/pymdown-extensions/extras/mermaid/#custom-loader
+// And https://github.com/facelessuser/pymdown-extensions/blob/main/docs/src/js/material-extra-3rdparty.js
+

template/mkdocs.yml.jinja

@@ -1,21 +1,46 @@
 ---
 site_name: "{{project_name}}"
 theme:
+  # https://www.mkdocs.org/user-guide/configuration/#theme
   name: material
+  icon:
+    logo: material/book-open-page-variant
   # palette:
   #  scheme: slate
   #  primary: cyan
   features:
     - content.tabs.link
+    - header.autohide      # maximum screen space during scrolling
+    - navigation.expand    # optimize user experience
+    - navigation.instant   # optimize user experience
+    - navigation.instant.progress
+    - navigation.tracking  # update address bar
+    - search.suggest       # suggest good completions
+    - content.code.copy    # enable copy to clipboard
 
-# for adding extra css/js see https://www.mkdocs.org/user-guide/customizing-your-theme/
+# extra css/js see https://www.mkdocs.org/user-guide/customizing-your-theme/
+extra_css: []
+extra_javascript: []
 
 plugins:
   - search
   - mknotebooks:
       execute: false
   - mermaid2:
       version: 11.4.1
+  - mkdocs_pymdownx_material_extras:
+    # https://pypi.org/project/mkdocs-pymdownx-material-extras
+
+markdown_extensions:
+  - pymdownx.superfences:
+      # https://mkdocs-mermaid2.readthedocs.io/en/latest/superfences
+      # custom code highlighting rules
+      custom_fences:
+        - name: mermaid
+          # disable code highlighting to display diagrams
+          format: !!python/name:pymdownx.superfences.fence_code_format
+          class: mermaid
+
   # TODO rebuild docs on schema change (https://github.com/dalito/linkml-project-copier/issues/39)
   # - gen-files:
   #     scripts:

template/pyproject.toml.jinja

@@ -23,6 +23,7 @@ dev = [
     "linkml>=1.9.3",
     "mkdocs-material>=8.2.8",
     "mkdocs-mermaid2-plugin>=1.1.1",
+    "mkdocs-pymdownx-material-extras>=2.5.6",
     "jupyter>=1.0.0",
     "mknotebooks>= 0.8.0",
 ]