Update documentation to clarify extra_javascript as failsafe (#111)

webdoc/docs/library.md

@@ -1,4 +1,4 @@
-# Specifying the Mermaid Library
+# Using the JavaScript Mermaid Library
 
 > _From version 1.1.0 of Mkdocs-Mermaid2_
 
@@ -20,9 +20,10 @@ plugins:
 
 The files can be found on [unpkg](https://unpkg.com/browse/mermaid@10.4.0/) or [jsdelivr.com](https://www.jsdelivr.com/package/npm/mermaid).
 
-Mkdocs-Mermaid2 will still insert the appropriate call to the library
+Mkdocs-Mermaid2 will still insert the appropriate call to the JavaScript library
 into the HTML page, according to the type of library (as all-in-one
-javascript function, or [ESM module](description.md/#automatic-insertion-of-the-javascript-library)), as well as the [initialization
+javascript function, or [ESM module](description.md/#automatic-insertion-of-the-javascript-library)),
+as well as the [initialization
 sequence](description.md/#initialization-sequence).
 
 To determine which version, it will use the extension:
@@ -92,17 +93,35 @@ https://cdn.jsdelivr.net/npm/mermaid@10.2.0/dist/mermaid.min.js
 
 ## Using `extra_javascript`
 
-!!! Warning "DEPRECATED"
+Mkdocs, by default, provides a standard mechanism for inserting a library into the
+HTML pages, which relies on the
+[parameter `extra_javascript` in the config file](https://mkdocs.readthedocs.io/en/859/user-guide/configuration/#extra_javascript).
+
 
+!!! Warning "DEPRECATED in default cases"
     As of version 1.1.0 of Mkdocs-Mermaid2, 
     using `extra_javascript` in the config file
-    to explictly call the javascript library is DEPRECATED.
-
+    as the default solution to explictly call 
+    the Mermaid javascript library is **DEPRECATED**.
 
+    Use instead the standard config of Mkdocs-Mermaid2 parameters.
+
+
+!!! Important "Failsafe mechanism"
+
+    However, `extra_javascript` was not kept only
+    as a backward compatibility measure.
+
+    Its purpose is now to be a **failsafe mechanism**.
+
+    **If Mkdocs-Mermaid2 detects a name of library that contains the
+    word `mermaid`, it will deactivate its own automatic/manual 
+    insertion mecanism and fall back on the standard mechanism of MkDocs.**
+
+    You can (and possibly should) use `extra_javascript` mechanism,
+    if the standard defaults
+    of MkDocs-Plugin do not match your needs.
 
-Mkdocs provides a standard mechanism for inserting a library into the
-HTML pages, which relies on the
-[parameter `extra_javascript` in the config file](https://mkdocs.readthedocs.io/en/859/user-guide/configuration/#extra_javascript).
 
 
 ```yaml
@@ -126,11 +145,20 @@ extra_javascript:
 
 (where the path is relative to the docs directory.)
 
-**If Mkdocs-Mermaid2 detects a name of library that contains the
-word `mermaid`, it will deactivate its own automatic/manual 
-insertion mecanism and fall back on the standard mechanism of MkDocs.**
 
+!!! Note "Going 'full manual'?"
+
+    If you feel that you need the flexibility of the `extra_javascript`
+    parameter,
+    you might start to weigh the pros and cons of using MkDocs-Mermaid2
+    as a plugin. 
 
+    You might want to go "full manual", 
+    **and deactivate the Mkdocs-Mermaid2 plugin.** 
+
+    Or on the contrary, if you are using the **Material theme**, you might consider
+    [using its default config for Mermaid](https://squidfunk.github.io/mkdocs-material/reference/diagrams/)
+       (if it works better for you).
 
 
 !!! Warning "Workaround for versions of MkDocs < 1.5"

webdoc/mkdocs.yml

@@ -13,12 +13,12 @@ theme:
     accent: pink
 repo_url: https://github.com/fralau/mkdocs-mermaid2-plugin
 edit_uri: edit/master/webdoc/docs/
-copyright: © Laurent Franceschetti, 2023. This work is licensed under CC BY-SA 4.0.
+copyright: © Laurent Franceschetti, 2024. This work is licensed under CC BY-SA 4.0.
 nav:
     - How to get started: index.md
     - Detailed description: description.md
     - Superfences: superfences.md
-    - Specifying the javascript library: library.md
+    - Using the Mermaid library: library.md
     - Tips and tricks: tips.md
     - troubleshooting.md
     - How to contribute: contribute.md