Add website for readthedocs, first version

.readthedocs.yml

@@ -0,0 +1,24 @@
+# .readthedocs.yml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Build documentation in the docs/ directory with Sphinx
+# sphinx:
+#   configuration: docs/conf.py
+
+# Python environment
+python:
+  install:
+    # these are needed, because they are not part of standard setup
+    - requirements: webdoc/extra_requirements.txt
+
+# Build documentation with MkDocs
+mkdocs:
+  configuration: webdoc/mkdocs.yml
+  fail_on_warning: false
+
+# Optionally build your docs in additional formats such as PDF and ePub
+formats: all

README.md

@@ -263,7 +263,7 @@ Where `js` is a subdirectory of the document directory (`docs`).
 If you are using a local javascript file, it is up to you to write the import,
 with a version of the Mermaid library > 10 e.g.:
 
-```yaml
+```javascript
 import mermaid from "https://unpkg.com/mermaid@10.0.2/dist/mermaid.esm.min.mjs"
 ```
 
@@ -302,7 +302,7 @@ By default, the plugin automatically inserts
 a Javascript command `mermaid.initialize();`
 in the HTML pages, which starts the interpretation.
 Sometimes, however, you may want to add some
-initialization commands (see [full list](https://github.com/knsv/mermaid/blob/master/docs/mermaidAPI.md#mermaidapi-configuration-defaults)).
+initialization commands (see [full list](https://github.com/mermaid-js/mermaid/blob/master/docs/config/setup/modules/mermaidAPI.md#mermaidapi-configuration-defaults)).
 
 For example, you could change the theme of the diagram, 
 using 'dark' instead of the default one. 
@@ -314,10 +314,6 @@ plugins:
     - mermaid2:
         arguments:
           theme: 'dark'
-
-
-extra_javascript:
-    - https://unpkg.com/mermaid/dist/mermaid.min.js
 ```
 
 ### Testing

mermaid2/plugin.py

@@ -96,7 +96,11 @@ def extra_mermaid_lib(self) -> str:
         """
         Provides the mermaid library defined in mkdocs.yml (if any)
         """
-        # as of mkdocs 1.5, extra_javascript is a list of objects; convert to string
+        # As of mkdocs 1.5, extra_javascript is a list of objects; 
+        # no longer a string. Call to str was used.
+        # Patched in 1.5.1, with __fspath___ method, 
+        # see https://github.com/mkdocs/mkdocs/issues/3310
+        # But we keep it, to guarantee it's a string. 
         extra_javascript = map(str, self.full_config.get('extra_javascript', []))
         for lib in extra_javascript:
             # get the actual library name
@@ -262,6 +266,10 @@ def on_post_page(self, output_content, config, page, **kwargs):
                 new_tag.string = "window.mermaidConfig = {default: %s}" % js_args
             else:
                 js_args =  pyjs.dumps(self.mermaid_args) 
-                new_tag.string="mermaid.initialize(%s);" % js_args
+                if self.mermaid_major_version >= 10:
+                    new_tag.string="mermaidAPI.initialize(%s);" % js_args
+                else:
+                    new_tag.string="mermaid.initialize(%s);" % js_args
+
             soup.body.append(new_tag)
         return str(soup)

setup.py

@@ -1,7 +1,7 @@
 from setuptools import setup, find_packages
 
 
-VERSION = '1.0.3'
+VERSION = '1.0.4'
 
 # required if you want to run tests
 # pip install 'mkdocs-mermaid2-plugin[test]'
@@ -31,7 +31,7 @@ def readme():
     author='pugong, Fralau',
     author_email='pugong.liu@gmail.com, fralau2035@yahoo.com',
     license='MIT',
-    python_requires='>=3.5',
+    python_requires='>=3.6',
     install_requires=[
         'setuptools>=18.5',
         'beautifulsoup4>=4.6.3',

webdoc/docs/contribute.md

@@ -0,0 +1,51 @@
+## Guidance
+
+1. Contributions are welcome.
+2. Before submitting an issue, consider this documentation, and particularly 
+   the [troubleshooting](../troubleshooting) section.
+3. Use the [Issues](https://github.com/fralau/mkdocs-mermaid2-plugin/issues) to signal a bug or propose a feature you believe is necessary.
+4. If this is a usage question, prefer the [discussions](https://github.com/fralau/mkdocs-mermaid2-plugin/discussions).
+5. **Before submitting a PR, always open an Issue and consider the answers.**
+6. As a rule, changes get a new version number;
+they are first [pushed on github](https://github.com/fralau/mkdocs-mermaid2-plugin), and then [deployed on pypi](https://pypi.org/project/mkdocs-mermaid2-plugin/).
+
+## Making a distinction between the software components
+When assessing issues or bugs, it is important to understand which 
+components are involved.
+
+```mermaid
+
+graph TD
+    mkdocs-mermaid["mkdocs-mermaid2 plugin"]
+    mkdocs-mermaid -- plugin of--> mkdocs
+    mkdocs-mermaid -- "uses (in browser)"--> Mermaid.js
+    mkdocs --> Superfences
+    mkdocs --> Material
+    mkdocs -.extra_javascript.-> Mermaid.js
+    Superfences -.custom fence.-> Mermaid.js
+    subgraph libraries
+    Mermaid.js
+    end
+    subgraph extensions
+    Superfences
+    end
+    subgraph themes
+    Material
+    Material -.-> Superfences
+    end
+    click mkdocs "https://www.mkdocs.org/" _blank
+    click Material "https://squidfunk.github.io/mkdocs-material/" _blank
+    click Superfences "https://facelessuser.github.io/pymdown-extensions/extensions/superfences/" _blank
+```
+
+## Credits
+
+mkdocs-mermaid2 is a fork from
+[Pugong Liu's excellent project](https://github.com/pugong/mkdocs-mermaid-plugin), 
+which is no longer maintained. This new plugin offers expanded documentation as
+well as new functions.
+
+It is also compatible with versions of the mermaid library > 10.0.
+
+Thanks to all the members of the community who participated to the 
+improvement of this project with ideas and PRs.

webdoc/docs/description.md

@@ -0,0 +1,117 @@
+## Steps for the preparation of an HTML page
+
+There are three steps in the preparation of the page:
+
+1. Setting up the HTML code that wraps the diagram.
+2. Inserting the javascript library (Mermaid.js) into the HTML page
+3. Inserting the call to the library
+
+## Conversion to HTML
+
+When converting the markdown into HTML, mkdocs normally inserts the
+Mermaid code (text) describing the diagram 
+into segments:
+
+    <pre class="mermaid">
+    <code>
+    ...
+    </code>
+    </pre>
+
+
+To make the HTML/css page more robust for most mkdocs themes,
+the mermaid plugin systematically converts
+those segments directly into `<div>` elements:
+
+    <div class="mermaid">
+    ...
+    </div>
+
+!!! Note "Superfences extension"
+    The principle remains the same 
+    when using the [Superfences](superfences) extension, except
+    when using the Material theme.
+
+    That extension is **not** mandatory.
+
+## Insertion of the Javascript Library
+The plugin then inserts a call to the
+[javascript library](https://github.com/mermaid-js/mermaid).
+
+By default, the plugin will use one of the latest versions of Mermaid.js.
+
+As already mentioned, you can specify, in the config file, the version
+of Mermaid.js required:
+
+```yaml
+- mermaid2:
+    version: '10.1.0'
+```
+
+
+!!! Note
+    The behavior of the plugin depends of the version of Mermaid.js, because
+    version 10.0.0 represents a significant change ([see changelog](https://github.com/mermaid-js/mermaid/blob/develop/CHANGELOG.md#1000)). 
+
+=== "Mermaid.js > 10.0.0"
+
+    > *From version 1.0 of mkdocs-mermaid2*
+
+    [For versions from 10.0.0 of the Mermaid javascript library, the plugin uses the ESM format](https://github.com/mermaid-js/mermaid/releases/tag/v10.0.0), since
+    it is the only one available. This requires a specific call from the HTML
+    page e.g.:
+    
+    ``` html
+    <script type="module">
+    import mermaid from "https://unpkg.com/mermaid@10.0.2/dist/mermaid.esm.min.mjs"
+    </script>
+    ```
+
+    The plugin automatically inserts this call.
+
+=== "Earlier versions"
+
+    For an earlier version of the Mermaid.js (<10),
+    the plugin uses the traditional call
+    from HTML:
+
+    ``` html
+    <script src="https://unpkg.com/mermaid@8.8.2/dist/mermaid.min.js">
+    </script>
+    ```
+
+    The plugin automatically inserts this call.
+
+
+## Call to the Library
+
+### Default sequence
+To start displaying of the diagrams, the plugin then automatically inserts 
+a separate call to initialize the Mermaid library:
+
+    <script>
+    mermaid.initialize()
+    </script>
+
+
+The user's browser will then read this code and render it on the fly.
+
+> No svg/png images are produced during the rendering of that graph.
+
+### Additional arguments to the Mermaid engine
+
+Sometimes, however, you may want to add some
+additional initialization commands (see [full list](https://github.com/knsv/mermaid/blob/master/docs/mermaidAPI.md#mermaidapi-configuration-defaults)).
+
+For example, you could change the theme of the diagram, 
+using 'dark' instead of the default one. 
+Simply add those arguments in the config file, e.g.
+
+```yaml
+plugins:
+    - search
+    - mermaid2:
+        arguments:
+          theme: 'dark'
+```
+