Enhance documentation

- upgraded mkdocs and dependencise (+ add mermaid)
- linted markdown
- add more details

doc/mkdocs.yml

@@ -28,7 +28,11 @@ markdown_extensions:
   - pymdownx.highlight:
       anchor_linenums: true
       use_pygments: false
-  - pymdownx.superfences
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:pymdownx.superfences.fence_code_format
 extra_css:
   - statics/main.css
 extra_javascript: