From 7db460e8c245fd2d32ba460c0e4b1b2014c4521e Mon Sep 17 00:00:00 2001 From: Laurent Franceschetti Date: Fri, 1 Sep 2023 14:09:02 +0200 Subject: [PATCH] Update documentation and bump to new version --- CHANGELOG.md | 10 ++ README.md | 32 ++++--- mermaid2/plugin.py | 5 +- setup.py | 2 +- webdoc/docs/description.md | 114 +++++++++++++++-------- webdoc/docs/index.md | 98 ++++++++++---------- webdoc/docs/library.md | 164 +++++++++++++++++++++++++++++++++ webdoc/docs/tips.md | 103 --------------------- webdoc/docs/troubleshooting.md | 20 +++- webdoc/mkdocs.yml | 8 +- 10 files changed, 345 insertions(+), 211 deletions(-) create mode 100644 webdoc/docs/library.md diff --git a/CHANGELOG.md b/CHANGELOG.md index d0cd740..443db87 100644 --- 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 index 0022b9e..f74886f 100755 --- a/README.md +++ b/README.md @@ -1,4 +1,6 @@ -# mkdocs-mermaid2-plugin +
+ +# 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.). + +
+ +--- * **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 -- [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) diff --git a/mermaid2/plugin.py b/mermaid2/plugin.py index fd8df8e..8bbfe31 100755 --- 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 index 4716150..e4fb531 100755 --- 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 index ee0603d..2fb8000 100644 --- 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. - 
-    
-    ...
-    
-
+## 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 +
+
+...
+
+
+``` -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 `
` elements: -
- ... -
+```html +
+... +
+``` !!! 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,17 +62,29 @@ 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: ` ``` - 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 ``` + 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 ` ``` -=== "Earlier versions" +=== "Traditional modules" - For versions of mermaid.js < 10, **two** calls to the ` diff --git a/webdoc/docs/index.md b/webdoc/docs/index.md index be4e035..c50528b 100644 --- a/webdoc/docs/index.md +++ b/webdoc/docs/index.md @@ -1,14 +1,17 @@ -# Mermaid2: A diagrams plugin for Mkdocs +# Mkdocs-Mermaid2
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/mermaid@10.4.0/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/mermaid@8.8.2/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: diff --git a/webdoc/docs/library.md b/webdoc/docs/library.md new file mode 100644 index 0000000..700bcd5 --- /dev/null +++ b/webdoc/docs/library.md @@ -0,0 +1,164 @@ +# Specifying the Mermaid Library + +> _From version 1.1.0 of Mkdocs-Mermaid2_ + +## Introduction +By default, MkDocs-Mermaid2 automatically inserts the proper calls to +[the Mermaid.js library, according to the correct version](../description/#insertion-of-the-javascript-library) (all-in one file, or ESM), +so that the diagrams are correctly interpreted. + +You may, however, specify your own version, using to the +`javascript` parameter of Mermaid2, +in the [config file of MkDocs](https://mkdocs.readthedocs.io/en/859/user-guide/configuration/). + +```yaml +plugins: + - search + - mermaid2: + javascript: https://unpkg.com/mermaid@10.4.0/dist/mermaid.esm.min.mjs +``` + +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 +into the HTML page, according to the type of library (as all-in-one +javascript function, or [ESM module](../description/#automatic-insertion-of-the-javascript-library)), as well as the [initialization +sequence](../description/#initialization-sequence). + +To determine which version, it will use the extension: + +File extension | Type | HTML Code +--- | -- | +`.js` | All-in-one javascript file (function) | `` + + +!!! Warning + In that case, the `version` parameter is ignored. + +## Deploying Mermaid.js with the MkDocs website + +In case you wish to use local version of the Mermaid.js library, +you can do so. + +```yaml +plugins: + - search + - mermaid2: + javascript: js/mermaid.min.js +``` + +The path is relative to the docs directory of Mkdocs. In the above example: + + mkdocs.yaml + ├─ docs/ + │ ├─ index.md + │ ├─ ... + │ ├─ js/ + │ │ ├─ mermaid.min.js + + +The typical way to download the library from unpkg or cdn.jsdelivr.net, +changing the version number to determine the version you want +(here: **10.2.0**): + +``` +https://cdn.jsdelivr.net/npm/mermaid@10.2.0/dist/mermaid.min.js +``` + +!!! Note + No explicit call to `mermaid.initialize()` is required, since it is + automatically inserted by the plugin. + +!!! Warning "Use the .js file" + The recommended way to do this, is to work with the file that contains + the traditional, all-in-one package that ends with `.js`. + + It **may** be possible to use the full ESM module (with a reference to + the script that ends with `.mjs`). That would require, however, + downloading the whole directory structure. Using the `.mjs` file + on its ownlwill definitely **not** work, since there will be broken + links. + + +## Using `extra_javascript` + +!!! Warning "DEPRECATED" + + As of version 1.1.0 of Mkdocs-Mermaid2, + using `extra_javascript` in the config file + to explictly call the javascript library is DEPRECATED. + + + +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 +extra_javascript: + - https://unpkg.com/mermaid@8.8.2/dist/mermaid.min.js +``` + +It still works for versions > 10: + +```yaml +extra_javascript: + - https://unpkg.com/mermaid@10.4.0/dist/mermaid.min.js +``` + +or (if using a local version): + +```yaml +extra_javascript: + - js/mermaid.min.js +``` + +(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.** + + + + +!!! Warning "Workaround for versions of MkDocs < 1.5" + + > _Versions of MkDocs < 1.5.0 were unable to call the ESM library._ + + The best solution is to call the `.js` file: + + ```yaml + extra_javascript: + - https://unpkg.com/mermaid@10.2.0/dist/mermaid.min.js + ``` + + + + If you **really** want to use the ESM module, + you could declare a local script file: + + ```yaml + extra_javascript: + - js/mermaidloader.js + ``` + + (where `js` is a subdirectory of the docs directory.) + + `mermaidloader.js` must contains the code for the import statement: + + ```javascript + import mermaid from "https://unpkg.com/mermaid@10.0.2/dist/mermaid.esm.min.mjs" + ``` + + + + + + + + + + diff --git a/webdoc/docs/tips.md b/webdoc/docs/tips.md index 057d48e..9caf71f 100644 --- a/webdoc/docs/tips.md +++ b/webdoc/docs/tips.md @@ -1,109 +1,6 @@ # Tips and Tricks -## Explicit declaration of the Mermaid library -### Introduction -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. - -If you do that, then plugin will refrain from inserting its own call -to the library. - -### Version of Mermaid.js < 10 - -All versions of mkdocs manage correctly the traditional call to javascript -code. - - -``` html - -``` - -You _may_ specify the mermaid library explicitly, as long as it is -call mermaid (independently of extension): - -```yaml -extra_javascript: - - https://unpkg.com/mermaid@8.8.2/dist/mermaid.min.js -``` - -This will be translated in the final HTML page as: - -```html - - ``` - -=== "mkdocs >= 1.5.0" - mkdocs correctly recognizes this case and will create the import statement. - - Treat this case normally: - - ```yaml - extra_javascript: - - https://unpkg.com/mermaid@8.8.2/dist/mermaid.min.js - ``` -=== "mkdocs < 1.5.0" - - Versions of mkdocs < 1.5.0 call the `