Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Mermaid Diagram Offline/Privacy Path Error #3742

Closed
5 tasks done
Vasperous opened this issue Mar 17, 2022 · 7 comments
Closed
5 tasks done

Mermaid Diagram Offline/Privacy Path Error #3742

Vasperous opened this issue Mar 17, 2022 · 7 comments
Labels
bug Issue reports a bug resolved Issue is resolved, yet unreleased if open

Comments

@Vasperous
Copy link
Sponsor

Contribution guidelines

I've found a bug and checked that ...

  • ... the problem doesn't occur with the mkdocs or readthedocs themes
  • ... the problem persists when all overrides are removed, i.e. custom_dir, extra_javascript and extra_css
  • ... the documentation does not mention anything about my problem
  • ... there are no open or closed issues that are related to my problem

Description

There appears to be an issue with the Mermaid resources used with the Offline and Privacy plugins. This causes the mermaid diagrams to not be rendered when running the mkdocs build command.

Here is the error from the console.

Failed to load resource: net::ERR_FILE_NOT_FOUND
2bundle.10bf1588.min.js:3 Uncaught ReferenceError: Invalid script: assets/externals/unpkg.com/mermaid@8.13.3/dist/mermaid.min.js
    at bundle.10bf1588.min.js:3:45290
    at e.n [as _subscribe] (bundle.10bf1588.min.js:3:19866)
    at e._trySubscribe (bundle.10bf1588.min.js:3:5506)
    at bundle.10bf1588.min.js:3:5429
    at ot (bundle.10bf1588.min.js:3:2783)
    at e.subscribe (bundle.10bf1588.min.js:3:5343)
    at bundle.10bf1588.min.js:3:30772
    at t.s._next (bundle.10bf1588.min.js:3:6820)
    at t.next (bundle.10bf1588.min.js:3:3140)
    at HTMLScriptElement.s (bundle.10bf1588.min.js:3:22621)

Expected behaviour

Mermaid diagrams should render as expected.

Actual behaviour

Mermaid diagrams are not correctly rendered and just display the actual diagram text.

Steps to reproduce

  1. Create an application with multiple layers/levels of pages
  2. Create a mermaid diagram in each page
  3. Run mkdocs -build

Package versions

  • Python: Python 3.10.0
  • MkDocs: mkdocs, version 1.2.3
  • Material: Version: 8.2.5+insiders.4.11.0

Configuration

site_name: 'My Test Project'
site_description: 'Test Project Description'
site_author: 'Tester'
site_url: ''

# Copyright
copyright: 'Copyright © 2022 Tester'

# If serving from a website you would want 'true', for offline you want false
use_directory_urls: false

nav:
  - Home:
    - Introduction: index.md
    - Layer 1: layer1/test1.md
    - Layer 2: layer1/layer2/test2.md
    - Layer 3: layer1/layer2/layer3/test3.md
    - Layer 4: layer1/layer2/layer3/layer4/test4.md
    - Layer 5: layer1/layer2/layer3/layer4/layer5/test5.md
    - Layer 6: layer1/layer2/layer3/layer4/layer5/layer6/test6.md

theme:
  name: 'material'
  font:
    text: 'Roboto'
    code: 'Roboto Mono'
  icon:
    admonition:
      note: octicons/tag-16
      abstract: octicons/checklist-16
      info: octicons/info-16
      tip: octicons/squirrel-16
      success: octicons/check-16
      question: octicons/question-16
      warning: octicons/alert-16
      failure: octicons/x-circle-16
      danger: octicons/zap-16
      bug: octicons/bug-16
      example: octicons/beaker-16
      quote: octicons/quote-16
  features:
    - content.tabs.link
    - navigation.indexes
    - navigation.tabs
    - navigation.tabs.sticky
    - navigation.top
    - navigation.tracking
    - search.highlight
    - search.share
    - search.suggest
    - toc.autohide

extra:
  generator: false

markdown_extensions:
  - abbr
  - admonition
  - attr_list
  - def_list
  - footnotes
  - meta
  - pymdownx.details
  - pymdownx.emoji:
      emoji_index: !!python/name:materialx.emoji.twemoji
      emoji_generator: !!python/name:materialx.emoji.to_svg
  - pymdownx.highlight:
      use_pygments: true
  - pymdownx.inlinehilite
  - pymdownx.keys
  - pymdownx.snippets:
      base_path: ext_md
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.tasklist:
      custom_checkbox: true
  - toc:
      permalink: '#'
      toc_depth: 5

plugins:
  - search
  - git-revision-date-localized:
      fallback_to_build_date: true
  - tags:
      tags_file: tags.md
  - offline
  - privacy

System information

  • Operating system: Mac OS
  • Browser: Brave & Chrome
@squidfunk
Copy link
Owner

Thanks for reporting - does the following file exist after you’ve built the site?

site/assets/externals/unpkg.com/mermaid@8.13.3/dist/mermaid.min.js

I’m currently on vacation, which means I don’t have a development environment at my disposal - I’ll check it as soon as I get back.

@Vasperous
Copy link
Sponsor Author

This is available:

│   └── unpkg.com
│       └── mermaid@8.13.3
│           └── dist
│               └── mermaid.min.js

Here is the whole folder.

assets
├── externals
│   ├── fonts.googleapis.com
│   │   └── css.css
│   ├── fonts.gstatic.com
│   │   └── s
│   │       ├── roboto
│   │       │   └── v29
│   │       │       ├── KFOjCnqEu92Fr1Mu51TjASc-CsTKlA.woff2
│   │       │       ├── KFOjCnqEu92Fr1Mu51TjASc0CsTKlA.woff2
│   │       │       ├── KFOjCnqEu92Fr1Mu51TjASc1CsTKlA.woff2
│   │       │       ├── KFOjCnqEu92Fr1Mu51TjASc2CsTKlA.woff2
│   │       │       ├── KFOjCnqEu92Fr1Mu51TjASc3CsTKlA.woff2
│   │       │       ├── KFOjCnqEu92Fr1Mu51TjASc5CsTKlA.woff2
│   │       │       ├── KFOjCnqEu92Fr1Mu51TjASc6CsQ.woff2
│   │       │       ├── KFOjCnqEu92Fr1Mu51TzBic-CsTKlA.woff2
│   │       │       ├── KFOjCnqEu92Fr1Mu51TzBic0CsTKlA.woff2
│   │       │       ├── KFOjCnqEu92Fr1Mu51TzBic1CsTKlA.woff2
│   │       │       ├── KFOjCnqEu92Fr1Mu51TzBic2CsTKlA.woff2
│   │       │       ├── KFOjCnqEu92Fr1Mu51TzBic3CsTKlA.woff2
│   │       │       ├── KFOjCnqEu92Fr1Mu51TzBic5CsTKlA.woff2
│   │       │       ├── KFOjCnqEu92Fr1Mu51TzBic6CsQ.woff2
│   │       │       ├── KFOkCnqEu92Fr1Mu51xEIzIFKw.woff2
│   │       │       ├── KFOkCnqEu92Fr1Mu51xFIzIFKw.woff2
│   │       │       ├── KFOkCnqEu92Fr1Mu51xGIzIFKw.woff2
│   │       │       ├── KFOkCnqEu92Fr1Mu51xHIzIFKw.woff2
│   │       │       ├── KFOkCnqEu92Fr1Mu51xIIzI.woff2
│   │       │       ├── KFOkCnqEu92Fr1Mu51xLIzIFKw.woff2
│   │       │       ├── KFOkCnqEu92Fr1Mu51xMIzIFKw.woff2
│   │       │       ├── KFOlCnqEu92Fr1MmSU5fABc4EsA.woff2
│   │       │       ├── KFOlCnqEu92Fr1MmSU5fBBc4.woff2
│   │       │       ├── KFOlCnqEu92Fr1MmSU5fBxc4EsA.woff2
│   │       │       ├── KFOlCnqEu92Fr1MmSU5fCBc4EsA.woff2
│   │       │       ├── KFOlCnqEu92Fr1MmSU5fCRc4EsA.woff2
│   │       │       ├── KFOlCnqEu92Fr1MmSU5fChc4EsA.woff2
│   │       │       ├── KFOlCnqEu92Fr1MmSU5fCxc4EsA.woff2
│   │       │       ├── KFOlCnqEu92Fr1MmWUlfABc4EsA.woff2
│   │       │       ├── KFOlCnqEu92Fr1MmWUlfBBc4.woff2
│   │       │       ├── KFOlCnqEu92Fr1MmWUlfBxc4EsA.woff2
│   │       │       ├── KFOlCnqEu92Fr1MmWUlfCBc4EsA.woff2
│   │       │       ├── KFOlCnqEu92Fr1MmWUlfCRc4EsA.woff2
│   │       │       ├── KFOlCnqEu92Fr1MmWUlfChc4EsA.woff2
│   │       │       ├── KFOlCnqEu92Fr1MmWUlfCxc4EsA.woff2
│   │       │       ├── KFOmCnqEu92Fr1Mu4WxKOzY.woff2
│   │       │       ├── KFOmCnqEu92Fr1Mu4mxK.woff2
│   │       │       ├── KFOmCnqEu92Fr1Mu5mxKOzY.woff2
│   │       │       ├── KFOmCnqEu92Fr1Mu72xKOzY.woff2
│   │       │       ├── KFOmCnqEu92Fr1Mu7GxKOzY.woff2
│   │       │       ├── KFOmCnqEu92Fr1Mu7WxKOzY.woff2
│   │       │       └── KFOmCnqEu92Fr1Mu7mxKOzY.woff2
│   │       └── robotomono
│   │           └── v13
│   │               ├── L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSV0mf0h.woff2
│   │               ├── L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSZ0mf0h.woff2
│   │               ├── L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSd0mf0h.woff2
│   │               ├── L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSh0mQ.woff2
│   │               ├── L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSt0mf0h.woff2
│   │               ├── L0xTDF4xlVMF-BfR8bXMIhJHg45mwgGEFl0_3vrtSM1J-gEPT5Ese6hmHSx0mf0h.woff2
│   │               ├── L0xdDF4xlVMF-BfR8bXMIjhOsXG-q2oeuFoqFrlnAIe2Imhk1T8rbociImtElOUlYIw.woff2
│   │               ├── L0xdDF4xlVMF-BfR8bXMIjhOsXG-q2oeuFoqFrlnAIe2Imhk1T8rbociImtEleUlYIw.woff2
│   │               ├── L0xdDF4xlVMF-BfR8bXMIjhOsXG-q2oeuFoqFrlnAIe2Imhk1T8rbociImtEluUlYIw.woff2
│   │               ├── L0xdDF4xlVMF-BfR8bXMIjhOsXG-q2oeuFoqFrlnAIe2Imhk1T8rbociImtEm-Ul.woff2
│   │               ├── L0xdDF4xlVMF-BfR8bXMIjhOsXG-q2oeuFoqFrlnAIe2Imhk1T8rbociImtEmOUlYIw.woff2
│   │               └── L0xdDF4xlVMF-BfR8bXMIjhOsXG-q2oeuFoqFrlnAIe2Imhk1T8rbociImtEn-UlYIw.woff2
│   └── unpkg.com
│       └── mermaid@8.13.3
│           └── dist
│               └── mermaid.min.js
├── images
│   └── favicon.png
├── javascripts
│   ├── bundle.10bf1588.min.js
│   ├── image-zoom.js
│   ├── lunr
│   │   ├── min
│   │   │   ├── lunr.ar.min.js
│   │   │   ├── lunr.da.min.js
│   │   │   ├── lunr.de.min.js
│   │   │   ├── lunr.du.min.js
│   │   │   ├── lunr.es.min.js
│   │   │   ├── lunr.fi.min.js
│   │   │   ├── lunr.fr.min.js
│   │   │   ├── lunr.hi.min.js
│   │   │   ├── lunr.hu.min.js
│   │   │   ├── lunr.it.min.js
│   │   │   ├── lunr.ja.min.js
│   │   │   ├── lunr.jp.min.js
│   │   │   ├── lunr.multi.min.js
│   │   │   ├── lunr.nl.min.js
│   │   │   ├── lunr.no.min.js
│   │   │   ├── lunr.pt.min.js
│   │   │   ├── lunr.ro.min.js
│   │   │   ├── lunr.ru.min.js
│   │   │   ├── lunr.stemmer.support.min.js
│   │   │   ├── lunr.sv.min.js
│   │   │   ├── lunr.th.min.js
│   │   │   ├── lunr.tr.min.js
│   │   │   ├── lunr.vi.min.js
│   │   │   └── lunr.zh.min.js
│   │   ├── tinyseg.js
│   │   └── wordcut.js
│   └── workers
│       └── search.5c9dbbf3.min.js
└── stylesheets
    ├── main.589a02ac.min.css
    └── palette.e6a45f82.min.css

17 directories, 88 files

@squidfunk
Copy link
Owner

So this turns out to be trickier than I thought, as it's a combination of things that lead to the observed behavior.

What happens:

  1. The privacy plugin analyzes the bundle.js resource (the Material for MkDocs application) and finds the URL unpkg.com/mermaid@8.13.3/dist/mermaid.min.js. Since it's a nested script inclusion, the privacy plugin must use the site_url to resolve to an absolute URL, which is also explained in the technical limitations. So far, so good.
  2. When building for offline usage, however, you must set site_url to an empty string, which means there's no absolute path to resolve. Thus, the nested script inclusion fails, as it is now a relative link, and depending on the level of nesting of Markdown documents it will not resolve correctly. The base for the link must be adjusted for each page that is called, which is done for extra_javascript when building via mkdocs build, but not for the nested script (can't be done).

This also leads to a (temporary?) mitigation: if you add the script explicitly in mkdocs.yml, it will be correctly downloaded and inlined into the build. Just add the following lines to mkdocs.yml:

extra_javascript:
  - https://unpkg.com/mermaid@8.13.3/dist/mermaid.min.js

I'm pretty sure that nested scripts will not work together with the offline plugin, but I have yet to investigate. I just wanted to provide a way of mitigating the issue at hand for you asap, so your build works again. Unfortunately, we can't just scan for nested scripts and add them to extra_javascript automatically, because we would need to alter the source of the including script somehow, and that's not possible without knowing what the script is doing. I guess the best way when using both plugins together and building for offline usage (as could be detected by the empty site URL) would be to exclude the script from being bundled and issue a warning that there's a nested script that's not bundled and must be included explicitly. But I have to invest more time into this first.

@squidfunk squidfunk added bug Issue reports a bug resolved Issue is resolved, yet unreleased if open needs investigation Issue must be investigated by the maintainers and removed bug Issue reports a bug labels Mar 23, 2022
@Vasperous
Copy link
Sponsor Author

Maybe I am misusing the combination of the privacy and offline plugins? I am trying to build to host on a private site which requires the documentation to be built for offline. In addition I build it so it can be downloaded for offline usage since my customers require offline access (plus everything loads faster).

@squidfunk
Copy link
Owner

squidfunk commented Mar 23, 2022

No, your use case should be perfectly fine, you just hit another yet unknown limitation which I need to investigate and document. It's fixable with a little manual work, as noted in my last comment.

If you're building your docs for online and offline usage, I recommend splitting the mkdocs.yml configuration using configuration inheritance and building separately for both cases. It's a good idea to only add the offline plugin and the fix above to the offline version because it won't incur any network penalty for downloading. This ensures that Mermaid.js in the online version is still only downloaded when necessary.

@squidfunk
Copy link
Owner

Fixed in 342aabc. This commit contains a patch for the privacy plugin that does the following:

If site_url is falsy (i.e. not set or set to an empty string), and the author did not add mermaid.js explicitly to extra_javascript, the mermaid.js script is automatically added. Since mermaid.js is now loaded relative to the page and not the application bundle.js, it will work at arbitrary depths. This is actually the only way to mitigate the missing absolute URL problem, which cannot be resolved for nested scripts as denoted in #3742 (comment).

You can either remove the fix in #3742 (comment) or keep it – the plugin should now handle both cases. This is only relevant for the privacy plugin. It's a special case that is necessary as Material for MkDocs automatically mounts mermaid.js.

@squidfunk squidfunk added bug Issue reports a bug and removed needs investigation Issue must be investigated by the maintainers labels Mar 26, 2022
@squidfunk
Copy link
Owner

Released as part of 8.2.8+insiders-4.12.0.

aceat64 added a commit to aceat64/website that referenced this issue Sep 14, 2022
When site_url isn't set (or is falsey) the privacy plugin will include
mermaid.js on _every page_ to mitigate an issue with offline site
generation.

squidfunk/mkdocs-material#3742
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
bug Issue reports a bug resolved Issue is resolved, yet unreleased if open
Projects
None yet
Development

No branches or pull requests

2 participants