steve/just-the-docs
1
0
Fork 0
mirror of https://github.com/snachodog/just-the-docs.git synced 2025-04-10 14:01:22 -06:00
Code Issues Packages Projects Releases Wiki Activity
just-the-docs/_config.yml
Matt Wang 5e5e2438d2
Fix mermaid v10, bundle all mermaid code in component (#1190) 
This PR does two things:

1. fixes using mermaid version `>= 10` from the CDN, by importing the ESM module instead
2. moves script loading code from `head.html` to the mermaid include

I've also added some light documentation to clarify how using mermaid with local paths should work (users should specify a version, and they should only use fully-minified bundles with no local references).

The nice thing about this approach is that it's a breaking change for nobody, and only adds functionality (v10 support). Eventually, we should remove support for mermaid <10, which should make this much easier!

Closes #1206.

## Context

In v10, Mermaid has implemented a few (admittedly, very frustrating to deal with) breaking changes:

1. they've removed CJS support, which is fine, *but*
2. that means that the `dist` they publish to JSDelivr now has a **different URL**: for versions `10.0.0` - `10.0.2`, **they do not have a minified bundle -- you have to load the ESM version with relative imports**
3. and, separately the `init` function has been deprecated

2 is really the issue, and so I've had to go into the code to now load mermaid by ESM by default when the user is on mermaid > v10.

I've tested this with:

- CDN version < 10 (v9)
- CDN version 10
- local path with version < 10 (v9)
- local path with version 10 (new: also loaded as an ESM module)

Separately, I chose to put all the mermaid stuff in one include because:

- I think @pdmosses requested something like this - it's a bit confusing that some mermaid code is *not* in the include, and this makes modular components ... more modular
- from a developer perspective, it's more clear what's happening with mermaid
- mermaid is not render-blocking, so it shouldn't be in the `head` anyways

---------

Co-authored-by: Peter Mosses <18308236+pdmosses@users.noreply.github.com>
2023-04-12 12:05:51 -07:00

186 lines
6.0 KiB
YAML
Raw Blame History

# Welcome to Jekyll!
#
# This config file is meant for settings that affect your whole site, values
# which you are expected to set up once and rarely edit after that. If you find
# yourself editing these this file very often, consider using Jekyll's data files
# feature for the data you need to update frequently.
#
# For technical reasons, this file is *NOT* reloaded automatically when you use
# 'jekyll serve'. If you change this file, please restart the server process.
# Site settings
# These are used to personalize your new site. If you look in the HTML files,
# you will see them accessed via {{ site.title }}, {{ site.github_repo }}, and so on.
# You can create any custom variable you would like, and they will be accessible
# in the templates via {{ site.myvariable }}.
title: Just the Docs
description: A Jekyll theme for documentation
baseurl: "/just-the-docs" # the subpath of your site, e.g. /blog
url: "https://just-the-docs.github.io" # the base hostname & protocol for your site, e.g. http://example.com
repository: just-the-docs/just-the-docs # for github-metadata
permalink: pretty
exclude:
# from https://github.com/jekyll/jekyll/blob/master/lib/site_template/_config.yml:
- .sass-cache/
- .jekyll-cache/
- gemfiles/
- Gemfile
- Gemfile.lock
- node_modules/
- vendor/bundle/
- vendor/cache/
- vendor/gems/
- vendor/ruby/
# specific to the theme website:
- bin/
- lib/
- "*.gemspec"
- "*.gem"
- LICENSE.txt
- package.json
- package-lock.json
- Rakefile
- README.md
- CODE_OF_CONDUCT.md
- docker-compose.yml
- Dockerfile
# theme test code
- fixtures/
# Set a path/url to a logo that will be displayed instead of the title
#logo: "/assets/images/just-the-docs.png"
# Enable or disable the site search
# Supports true (default) or false
search_enabled: true
search:
# Split pages into sections that can be searched individually
# Supports 1 - 6, default: 2
heading_level: 2
# Maximum amount of previews per search result
# Default: 3
previews: 2
# Maximum amount of words to display before a matched word in the preview
# Default: 5
preview_words_before: 3
# Maximum amount of words to display after a matched word in the preview
# Default: 10
preview_words_after: 3
# Set the search token separator
# Default: /[\s\-/]+/
# Example: enable support for hyphenated search words
tokenizer_separator: /[\s/]+/
# Display the relative url in search results
# Supports true (default) or false
rel_url: true
# Enable or disable the search button that appears in the bottom right corner of every page
# Supports true or false (default)
button: false
# For copy button on code
enable_copy_code_button: true
# By default, consuming the theme as a gem leaves mermaid disabled; it is opt-in
mermaid:
# Version of mermaid library
# Pick an available version from https://cdn.jsdelivr.net/npm/mermaid/
version: "9.1.6"
# Put any additional configuration, such as setting the theme, in _includes/mermaid_config.js
# See also docs/ui-components/code
# To load mermaid from a local library, also use the `path` key to specify the location of the library; e.g.
# for (v10+):
# path: "/assets/js/mermaid.esm.min.mjs"
# for (<v10):
# path: "/assets/js/mermaid.min.js"
# Note: copy both `mermaid.esm.min.mjs` (v10+) or `mermaid.min.js` (<v10) and the associated `.map` file from the specified version of `mermaid/dist` to `/assets/js/`.
# Enable or disable heading anchors
heading_anchors: true
# Aux links for the upper right navigation
aux_links:
"Just the Docs on GitHub":
- "//github.com/just-the-docs/just-the-docs"
# Makes Aux links open in a new tab. Default is false
aux_links_new_tab: false
# Sort order for navigation links
# nav_sort: case_insensitive # default, equivalent to nil
nav_sort: case_sensitive # Capital letters sorted before lowercase
# External navigation links
nav_external_links:
- title: Just the Docs on GitHub
url: https://github.com/just-the-docs/just-the-docs
# Footer content
# appears at the bottom of every page's main content
# Back to top link
back_to_top: true
back_to_top_text: "Back to top"
footer_content: "Copyright &copy; 2017-2020 Patrick Marsceill. Distributed by an <a href=\"https://github.com/just-the-docs/just-the-docs/tree/main/LICENSE.txt\">MIT license.</a> <a href=\"https://www.netlify.com/\">This site is powered by Netlify.</a>"
# Footer last edited timestamp
last_edit_timestamp: true # show or hide edit time - page must have `last_modified_date` defined in the frontmatter
last_edit_time_format: "%b %e %Y at %I:%M %p" # uses ruby's time format: https://ruby-doc.org/stdlib-2.7.0/libdoc/time/rdoc/Time.html
# Footer "Edit this page on GitHub" link text
gh_edit_link: true # show or hide edit this page link
gh_edit_link_text: "Edit this page on GitHub"
gh_edit_repository: "https://github.com/just-the-docs/just-the-docs" # the github URL for your repo
gh_edit_branch: "main" # the branch that your docs is served from
# gh_edit_source: docs # the source that your files originate from
gh_edit_view_mode: "tree" # "tree" or "edit" if you want the user to jump into the editor immediately
# Color scheme currently only supports "dark", "light"/nil (default), or a custom scheme that you define
color_scheme: nil
callouts_level: quiet # or loud
callouts:
highlight:
color: yellow
important:
title: Important
color: blue
new:
title: New
color: green
note:
title: Note
color: purple
warning:
title: Warning
color: red
# Google Analytics Tracking (optional)
# Supports a CSV of tracking ID strings (eg. "UA-1234567-89,G-1AB234CDE5")
# Note: the main Just the Docs site does *not* use Google Analytics.
# ga_tracking: UA-2709176-10,G-5FG1HLH3XQ
# ga_tracking_anonymize_ip: true # Use GDPR compliant Google Analytics settings (true/nil by default)
plugins:
- jekyll-seo-tag
- jekyll-github-metadata
kramdown:
syntax_highlighter_opts:
block:
line_numbers: false
compress_html:
clippings: all
comments: all
endings: all
startings: []
blanklines: false
profile: false
# ignore:
# envs: all
Reference in New Issue View Git Blame Copy Permalink