Update documentation and bump to new version

fralau · Sep 1, 2023 · 7db460e · 7db460e
1 parent e48544e
commit 7db460e
Show file tree

Hide file tree

Showing 10 changed files with 345 additions and 211 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,16 @@ All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 1.1.0, 2023-09-01
+
+Added: Parameter `javascript` in config file for optionally specifying the
+    URL or path of the Mermaid javascript library.
+
+Changed: Parameter `extra_javascript` in config file is DEPRECATED,
+    for optionally specifying the URL or path of the Mermaid javascript library
+
+Changed: Updated documentation.
+
 ## 1.0.8, 2023-08-09
 
 Fixed: Arguments of config file not taken into consideration,

diff --git a/README.md b/README.md
@@ -1,4 +1,6 @@
-# mkdocs-mermaid2-plugin
+<div align="center">
+
+# Mkdocs-Mermaid2
 
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) 
@@ -7,9 +9,11 @@
 ![Downloads(PyPI)](https://img.shields.io/pypi/dm/mkdocs-mermaid2-plugin)
 
 
-An [MkDocs](https://www.mkdocs.org/) plugin that renders textual graph
-descriptions into [Mermaid](https://mermaid-js.github.io/mermaid) graphs
-(flow charts, sequence diagrams, pie charts, etc.).
+An [MkDocs](https://www.mkdocs.org/) plugin that renders [Mermaid](https://mermaid-js.github.io/mermaid) text descriptions into diagrams (flow charts, sequence diagrams, pie charts, etc.).
+
+</div>
+
+---
 
 * **See the [mkdocs-mermaid2 documentation on Read The Docs](https://mkdocs-mermaid2.readthedocs.io).**
 * See the [package on Pypi](https://pypi.org/project/mkdocs-mermaid2-plugin/).
@@ -26,15 +30,17 @@ markdown-toc -i README.md
 
 <!-- toc -->
 
-- [Introduction](#introduction)
-- [Installation](#installation)
-  * [Automatic](#automatic)
-  * [Manual](#manual)
-  * [Test](#test)
-- [Configuration](#configuration)
-  * [Basic configuration](#basic-configuration)
-  * [Specifying the version of the Mermaid library](#specifying-the-version-of-the-mermaid-library)
-- [For more information](#for-more-information)
+- [Mkdocs-Mermaid2](#mkdocs-mermaid2)
+  - [Introduction](#introduction)
+  - [Installation](#installation)
+    - [Automatic](#automatic)
+    - [Manual](#manual)
+    - [Test](#test)
+  - [Configuration](#configuration)
+    - [Basic configuration](#basic-configuration)
+    - [Specifying the version of the Mermaid library](#specifying-the-version-of-the-mermaid-library)
+    - [Additional settings for the Material theme](#additional-settings-for-the-material-theme)
+  - [For more information](#for-more-information)
 
 <!-- tocstop -->
 

diff --git a/mermaid2/plugin.py b/mermaid2/plugin.py
@@ -16,9 +16,10 @@
 # ------------------------
 # Constants and utilities
 # ------------------------
-# the default (recommended) mermaid lib
-JAVASCRIPT_VERSION = '10.1.0'
+# the default (recommended) mermaid lib:
+JAVASCRIPT_VERSION = '10.4.0'
 JAVASCRIPT_PRE_10 = "https://unpkg.com/mermaid@%s/dist/mermaid.min.js"
+# New format (ESM):
 JAVASCRIPT = "https://unpkg.com/mermaid@%s/dist/mermaid.esm.min.mjs"
 
 

diff --git a/setup.py b/setup.py
@@ -1,7 +1,7 @@
 from setuptools import setup, find_packages
 
 
-VERSION = '1.0.9'
+VERSION = '1.1.0'
 
 # required if you want to run tests
 # pip install 'mkdocs-mermaid2-plugin[test]'

diff --git a/webdoc/docs/description.md b/webdoc/docs/description.md
@@ -1,40 +1,54 @@
+# Detailed description of the page production process
+
 ## Steps for the preparation of an HTML page
 
-There are three steps in the preparation of the page:
+There are three steps in the preparation of the HTML 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
+```mermaid
+flowchart TD
+    subgraph Page [Page production]
+    HTML(1. Setting up the HTML tags around the diagram.) --> JS("2. Inserting the call to Mermaid.js")
+    JS --> Init(3. Initialization/customization)
+    end
 
-## Conversion to HTML
+```
 
-When converting the markdown into HTML, mkdocs normally inserts the
-Mermaid code (text) describing the diagram 
-into segments:
+When the webserver serves the statig html page,
+the Mermaid.js library is executed in the user's browser, to render the diagram.
 
-    <pre class="mermaid">
-    <code>
-    ...
-    </code>
-    </pre>
+## Conversion to HTML
 
+When converting the markdown into HTML, MkDocs normally inserts the
+Mermaid code (text) describing the diagram 
+into segments, which will then be processed by the Mermaid.js library
+(in the user's browser):
+
+```html
+<pre class="mermaid">
+<code>
+...
+</code>
+</pre>
+```
 
-To make the HTML/css page more robust for most mkdocs themes,
-the mermaid plugin systematically converts
+To make the HTML/css page more robust for most MkDocs themes,
+the Mkdocs-Mermaid2 plugin systematically converts
 those segments directly into `<div>` elements:
 
-    <div class="mermaid">
-    ...
-    </div>
+```html
+<div class="mermaid">
+...
+</div>
+```
 
 !!! Note "Superfences extension"
     The principle remains the same 
-    when using the [Superfences](superfences) extension, except
-    when using the Material theme.
+    when using the [Superfences](superfences) extension.
 
-    That extension is **not** mandatory.
+    That extension is **not** mandatory, except
+    when using the Material theme.
 
-## Insertion of the Javascript Library
+## Automatic insertion of the Javascript Library
 The plugin then inserts a call to the
 [javascript library](https://github.com/mermaid-js/mermaid).
 
@@ -48,49 +62,71 @@ of Mermaid.js required:
     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)). 
+    Mkdocs-Macros inserts the Mermaid.js library into the HTML page
+    **only** when a Mermaid diagram is detected in the markdown page.
 
-=== "Mermaid.js > 10.0.0"
+!!! Warning "Change of distribution format"
+    The behavior of the plugin depends of the version of Mermaid.js.
 
-    > *From version 1.0 of mkdocs-mermaid2*
+    [As of version 10 of the Mermaid javascript library, the plugin uses the ESM format for distribution](https://github.com/mermaid-js/mermaid/releases/tag/v10.0.0) (see also the [changelog](https://github.com/mermaid-js/mermaid/blob/develop/CHANGELOG.md#1000)).
 
-    [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
+    More information can be found on [ECMAScript Module](https://nodejs.org/api/esm.html#modules-ecmascript-modules)
+    (or **ESM**), but for our purposes:
+
+    1. **The main file is recognizable because it has the `.mjs` extension.**
+    2. The HTML call must have the form: `<script src="<URL>", type="module">`
+    3. A module in ESM format is not a single file, but a hierarchy of directories/files.
+
+    **MkDocs-Mermaid2, as of version 1.0, takes this difference into account.**
+
+=== "ESM Library"
+
+    > For versions of MkDocs-Mermaid2 >= 1 and versions of Mermaid2.js >= 10
+
+    This requires a specific call from the HTML
     page e.g.:
 
     ``` html
     <script src="https://unpkg.com/[email protected]/dist/mermaid.esm.min.mjs" type="module">
     </script>
     ```
 
-
     The plugin automatically inserts this call.
 
-=== "Earlier versions"
+=== "All-in-one Library"
 
     For an earlier version of the Mermaid.js (<10),
-    the plugin uses the traditional call
-    from HTML:
+    the plugin continues to use the traditional version, which is an **all-in-one file**.
+
+    Those library files are recognizable because they have the `.js` extension.
+
+    The call in the HTML page is:
 
     ``` html
     <script src="https://unpkg.com/[email protected]/dist/mermaid.min.js">
     mermaid.initialize()
     </script>
     ```
 
+
     The plugin automatically inserts this call.
 
+    ** This is still a valid method.** (Even though the very first versions after 10.0.0 no longer provided
+    this file, later versions have resumed providing it.)
 
-## Call to the Library
+
+
+
+## Initialization sequence
 
 ### Default sequence
 To start displaying of the diagrams, the plugin then automatically inserts 
 a separate call to initialize the Mermaid library:
 
-
+```javascript
+mermaid.initialize()
+```
 
 The user's browser will then read this code and render it on the fly.
 
@@ -124,10 +160,10 @@ plugins:
 
 The plugin then automatically adds the initialization sequence:
 
-=== "mermaid.js >= 10.0"
+=== "ESM modules"
 
     Both `import` and `mermaid.initialize()` must be in the same `<script>`
-    tag.
+    tag. This is the code produced by the plugin:
 
     ```html
     <script type="module">import mermaid from "https://unpkg.com/[email protected]/dist/mermaid.esm.min.mjs";
@@ -144,9 +180,9 @@ The plugin then automatically adds the initialization sequence:
     });
     </script>
     ```
-=== "Earlier versions"
+=== "Traditional modules"
 
-    For versions of mermaid.js < 10, **two** calls to the `<script>` tag are required.
+    For traditional (all-in-one file) javascript modules, **two** calls to the `<script>` tag are required. This is the code produced by the plugin:
 
     ```html
     <script src="https://unpkg.com/[email protected]/dist/mermaid.min.js"></script>

diff --git a/webdoc/docs/index.md b/webdoc/docs/index.md
@@ -1,14 +1,17 @@
-# Mermaid2: A diagrams plugin for Mkdocs
+# Mkdocs-Mermaid2<br>A diagrams plugin for Mkdocs { align=center }
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) 
+---
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![PyPI](https://img.shields.io/pypi/v/mkdocs-mermaid2-plugin)](https://pypi.org/project/mkdocs-mermaid2-plugin/)
 ![Github](https://img.shields.io/github/v/tag/fralau/mkdocs-mermaid2-plugin?label=github%20tag)
 ![Downloads(PyPI)](https://img.shields.io/pypi/dm/mkdocs-mermaid2-plugin)
 
+
 ## Introduction
-**Mermaid2** is a plugin for the [MkDocs](https://www.mkdocs.org/) 
+**Mkdocs-Mermaid2** is a plugin for the [MkDocs](https://www.mkdocs.org/) 
 static sites generator, which allows you 
-to render Mermaid diagrams inserted in the markdown pages.
+to render Mermaid diagrams inserted (as text) into the markdown pages.
 
 - [The official repository of Mermaid2 is on github.](https://github.com/fralau/mkdocs-mermaid2-plugin)
 - [Mermaid2 is available from Pypi.](https://pypi.org/project/mkdocs-mermaid2-plugin/)
@@ -153,6 +156,47 @@ plugins:
     If you declare plugins in the config file, you need to declare _all_ of them, 
     including `search` (which would otherwise have been installed by default.)
 
+
+
+
+### Specifying the version of the Mermaid library
+
+By default, the plugin selects a version of the Mermaid javascript library
+that is known to work (some versions work better than others).
+
+You may specify a different version of the Mermaid library, like so:
+
+```yaml
+plugins:
+  - search
+  - mermaid2:
+      version: 10.0.2
+```
+
+The plugin will insert the correct call to the javascript library
+inside the final HTML page.
+
+
+### Specifying your own Mermaid library
+
+By default, mkdocs-mermaid2 automatically inserts the proper calls to
+Mermaid.js (according to the correct version),
+so that the diagrams are correctly interpreted.
+
+You may, however, specify your own explicit call:
+
+```yaml
+plugins:
+  - search
+  - mermaid2:
+      javascript: https://unpkg.com/[email protected]/dist/mermaid.esm.min.mjs
+```
+
+For more details, [see the relative page](../library).
+
+
+
+
 ### Use of the Material theme
 
 !!! Note
@@ -210,52 +254,6 @@ The result would be as follows, for the diagrams above:
 
 
 
-### Specifying the version of the Mermaid library
-
-By default, the plugin selects a version of the Mermaid javascript library
-that is known to work (some versions work better than others).
-
-You may specify a different version of the Mermaid library, like so:
-
-```yaml
-plugins:
-  - search
-  - mermaid2:
-      version: 10.0.2
-```
-
-The plugin will insert the correct call to the javascript library
-inside the final HTML page.
-
-
-### Specifying your own Mermaid library
-
-By default, mkdocs-mermaid2 automatically inserts the proper calls to
-Mermaid.js (according to the correct version),
-so that the diagrams are correctly interpreted.
-
-You may, however, specify your own call, with the use of the `extra_javascript`
-directive in the configuration file. **This is considered as a hack, 
-if the default procedure doesn't work.**
-
-If you do that, then the plugin will refrain from inserting its own call 
-to the Mermaid.js.
-
-```yaml
-extra_javascript:
-    - https://unpkg.com/[email protected]/dist/mermaid.min.js
-```
-
-
-
-!!! Warning
-    To make this work with versions of the library > 10
-    with the `mjs` extension, you need a version of mkdocs > 1.5.0.
-
-    With versions of mkdocs < 1.5.0, 
-    see the [troubleshooting section](troubleshooting/#explicit-calls-of-the-mermaid-library).
-
-
 ### Testing
 
 To test your website with a diagram, restart the mkdocs server: