From e2f1546c61c1af6977162ce16ff65fd01f054725 Mon Sep 17 00:00:00 2001 From: Matt Wang Date: Thu, 11 Aug 2022 19:34:15 -0700 Subject: [PATCH] `mermaid`: refactor config to use `mermaid_config.js` include, only require `mermaid.version` in `_config.yml` (#909) This PR has a bit of scope creep! This PR now: - changes the mermaid opt-in logic to only check for the existence of a `mermaid` key instead of `mermaid != false`: this resolves the follow-up in #857 - changes the behaviour of mermaid configuration - instead of using `mermaid_init.html` with default settings, makes the include `mermaid_config.js` - the include is loaded directly into the contents of `mermaid_initialize` - by default, it is an empty object (i.e. `{}`), triggering the defaults - updates docs - adds an example to the markdown kitchen sink It does significantly change the interface provided in #857, and I apologize for the confusion. However, given the discussion in this PR, I think it's the best move forward! --- _config.yml | 28 +++++------------- _includes/head.html | 2 +- _includes/mermaid_config.js | 1 + _includes/mermaid_init.html | 58 ------------------------------------- _layouts/default.html | 8 +++-- docs/configuration.md | 24 +++++---------- docs/index-test.md | 15 +++++++++- docs/ui-components/code.md | 31 ++++++++++++++++++-- 8 files changed, 66 insertions(+), 101 deletions(-) create mode 100644 _includes/mermaid_config.js delete mode 100644 _includes/mermaid_init.html diff --git a/_config.yml b/_config.yml index 5944d041d403..348c9845cb02 100644 --- a/_config.yml +++ b/_config.yml @@ -51,26 +51,14 @@ search: # Supports true or false (default) button: false -# Enable or disable support for mermaid diagrams (https://mermaid-js.github.io/mermaid/) -# Supports true or false (default) -mermaid_enabled: false -mermaid: - # Version of mermaid library - # Pick an available version from https://cdn.jsdelivr.net/npm/mermaid/ - version: "9.1.3" - # Configured theme of mermaid diagrams - # Pick an avaiable theme from https://mermaid-js.github.io/mermaid/#/theming - theme: "default" - # Additional configuration available matching pattern as defined in https://mermaid-js.github.io/mermaid/#/./Setup. - # For example, - # logLevel: 'fatal', - # sequence: - # diagramMarginX: 50 - # actorMargin: 50 - # gantt: - # barGap: 4 - # topPadding: 50 - +# To enable support for mermaid diagrams (https://mermaid-js.github.io/mermaid/), +# uncomment the `mermaid` and `version` keys below +# mermaid: +# # Version of mermaid library +# # Pick an available version from https://cdn.jsdelivr.net/npm/mermaid/ +# version: "9.1.3" +# # Put any additional configuration, such as setting the theme, in _includes/mermaid_config.js +# # See also docs/ui-components/code # Enable or disable heading anchors heading_anchors: true diff --git a/_includes/head.html b/_includes/head.html index 1b4f7b7fc6d1..ef48ba93d976 100644 --- a/_includes/head.html +++ b/_includes/head.html @@ -30,7 +30,7 @@ {% endif %} - {% if site.mermaid_enabled != false %} + {% if site.mermaid %} {% endif %} diff --git a/_includes/mermaid_config.js b/_includes/mermaid_config.js new file mode 100644 index 000000000000..0967ef424bce --- /dev/null +++ b/_includes/mermaid_config.js @@ -0,0 +1 @@ +{} diff --git a/_includes/mermaid_init.html b/_includes/mermaid_init.html deleted file mode 100644 index 327dfdf64bcd..000000000000 --- a/_includes/mermaid_init.html +++ /dev/null @@ -1,58 +0,0 @@ - diff --git a/_layouts/default.html b/_layouts/default.html index a09a2a477c9c..6cebe98b8788 100644 --- a/_layouts/default.html +++ b/_layouts/default.html @@ -215,7 +215,11 @@

Table of contents

{% endif %} -{% if site.mermaid_enabled != false %} - {%- include mermaid_init.html -%} +{% if site.mermaid %} + {% endif %} diff --git a/docs/configuration.md b/docs/configuration.md index 041805c2429a..78f609ee404d 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -60,30 +60,18 @@ search: ``` ## Mermaid Diagrams -See [Code]({{ site.baseurl }}{% link docs/ui-components/code.md %}#mermaid-diagram-code-blocks) for more information. + +The minimum configuration requires the key for `version` ([from jsDelivr](https://cdn.jsdelivr.net/npm/mermaid/)) in `_config.yml`: ```yaml -# Enable or disable support for mermaid diagrams (https://mermaid-js.github.io/mermaid/) -# Supports true or false (default) -mermaid_enabled: false mermaid: # Version of mermaid library # Pick an available version from https://cdn.jsdelivr.net/npm/mermaid/ version: "9.1.3" - # Configured theme of mermaid diagrams - # Pick an avaiable theme from https://mermaid-js.github.io/mermaid/#/theming - theme: "default" - # Additional configuration available matching pattern as defined in https://mermaid-js.github.io/mermaid/#/./Setup. - # For example, - # logLevel: 'fatal', - # sequence: - # diagramMarginX: 50 - # actorMargin: 50 - # gantt: - # barGap: 4 - # topPadding: 50 ``` +See [the Code documentation]({{ site.baseurl }}{% link docs/ui-components/code.md %}#mermaid-diagram-code-blocks) for more configuration options and information. + ## Aux links ```yaml @@ -186,7 +174,7 @@ A paragraph... ``` [^dark]: - If you use the `dark` color scheme, this callout uses `$red-300` for the background, and `$red-000` for the title. + If you use the `dark` color scheme, this callout uses `$red-300` for the background, and `$red-000` for the title. The colors `grey-lt`, `grey-dk`, `purple`, `blue`, `green`, `yellow`, and `red` are predefined; to use a custom color, you need to define its `000` and `300` levels in your SCSS files. For example, to use `pink`, add the following to your `_sass/custom/custom.scss` file: @@ -261,6 +249,7 @@ just_the_docs: # Supports true or false (default) # search_exclude: true ``` + The navigation for all your normal pages (if any) is displayed before those in collections. You can reference multiple collections. @@ -282,6 +271,7 @@ just_the_docs: tutorials: name: Tutorials ``` + When *all* your pages are in a single collection, its name is not displayed. The navigation for each collection is a separate name space for page titles: a page in one collection cannot be a child of a page in a different collection, or of a normal page. diff --git a/docs/index-test.md b/docs/index-test.md index 06aeffc86747..b0d4dff8b6b1 100644 --- a/docs/index-test.md +++ b/docs/index-test.md @@ -71,7 +71,7 @@ end [This is a very long link which wraps and therefore doesn't overflow even when it comes at the beginning](.) of the line. - + - [This is a very long link which wraps and therefore doesn't overflow the line when used first in an item ](.) in a list. @@ -298,6 +298,19 @@ class conditions(object): Long, single-line code blocks should not wrap. They should horizontally scroll if they are too long. This line should be long enough to demonstrate this. ``` +### Mermaid Diagrams + +The following code is displayed as a diagram only when a `mermaid` key supplied in `_config.yml`. + +```mermaid +graph TD; + A-->B; + A-->C; + B-->D; + C-->D; +``` + + ``` The final element. ``` diff --git a/docs/ui-components/code.md b/docs/ui-components/code.md index 0ea9b71fde0d..a0d57077a111 100644 --- a/docs/ui-components/code.md +++ b/docs/ui-components/code.md @@ -91,9 +91,36 @@ To demonstrate front end code, sometimes it's useful to show a rendered example ## Mermaid diagram code blocks -[Mermaid](https://mermaid-js.github.io/mermaid/) allows you to add diagrams and visualizations using Markdown code blocks. You can turn on support for mermaid by adding `mermaid_enabled: true` to your \_config.yml. +[Mermaid](https://mermaid-js.github.io/mermaid/) allows you to add diagrams and visualizations using Markdown code blocks. You can turn on support for mermaid by adding a `mermaid` key to your `_config.yml`. -The markdown for a simple flowchart example might look like the following: +The minimum configuration requires a `version` key (matching a version in [jsDelivr](https://cdn.jsdelivr.net/npm/mermaid/)): + +```yaml +mermaid: + # Version of mermaid library + # Pick an available version from https://cdn.jsdelivr.net/npm/mermaid/ + version: "9.1.3" +``` + +Additional configuration options are loaded through `_includes/mermaid_config.js`. By default, the contents of the file are the empty object: + +```js +// _includes/mermaid_config.js +{} +``` + +This loads the default settings. + +The contents of this object should follow [mermaid's configuration API](https://mermaid-js.github.io/mermaid/#/./Setup?id=configuration). For example, to override the theme, change `_includes/mermaid_config.js` to: + +```js +// _includes/mermaid_config.js +{ + theme: "forest" +} +``` + +Once mermaid is installed, it can be used in markdown files. The markdown for a simple flowchart example might look like the following: {% highlight markdown %} ```mermaid