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/[email protected]/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:/knsv/mermaid/blob/master/docs/mermaidAPI.md#mermaidapi-configuration-defaults)).
+initialization commands (see [full list](https:/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:/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='[email protected], [email protected]',
  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:/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:/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:/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:/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:/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:/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:/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/[email protected]/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/[email protected]/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:/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'
+```
+