steve/just-the-docs
1
0
Fork 0
mirror of https://github.com/snachodog/just-the-docs.git synced 2025-09-17 14:43:32 -06:00
Code Issues Packages Projects Releases Wiki Activity

mermaid: refactor config to use mermaid_config.js include, only require mermaid.version in _config.yml (#909)

Browse Source 
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!
This commit is contained in:
Matt Wang
2022-08-11 19:34:15 -07:00
committed by GitHub
parent 1d15ea3b84
commit e2f1546c61
8 changed files with 66 additions and 101 deletions
Download Patch File Download Diff File Expand all files Collapse all files

24
docs/configuration.md
View File

@@ -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.