Open BansheeHero opened 4 months ago
Thank you for your contribution! This is very appreciated.
Came for the same issue. I wanted to remove use of extra_javascript and extra_css but since I'm building our documentation in an isolated network, the build fails checking the URL of mermaid on unpkg. I had a look at #102 @BansheeHero and it looks good but I would recommend a simpler strategy to allow not even checking the URL and warn that it might lead to non-functional graphs. The reason is that it would avoid doing any connections at all thus no exception handling, timeouts, etc to deal with. What do you think?
Thank you. The business case makes sense and the approach appears sensible.
I would advise against implementing a skip without making sure the admin is aware of the issue. There is a gap between ignoring the network problem and not being aware of it at all. (EDIT: Remember that we are dealing with injecting remote javascript to client's browsers. This is not something to leave to as a warning that is skipped by default.)
Anyway, there are two PRs I tried to made in the same style as the original repo. One is correct reporting and the other is the way I worked around the problem. I split them because I consider one to be a bug and the other enhancement.
Let me know if there is something I can do better.
@BansheeHero Your approach has some good points.You complemented it with two procedures warning()
and critical()
, something I had just done with Mkdocs-Macros (https://github.com/fralau/mkdocs-macros-plugin/commit/4f96dd5b56817275fa7d5597b4bbac394d07b20e), in a slightly more general way.
Maybe you wish to compare?
The question we need to ask at this point, is how we want this issue to initially appear in the build process: as a warning to the admin (which would break only if the --strict
option is used), or as an error?
(For more background, see https://github.com/fralau/mkdocs-macros-plugin/issues/226.)
Impact: Cannot build or serve on some network isolated machines. Issue: Code expects that request is always made and only evaluates the final HTTP code:
Discovered on ZScaler networks, where the product fails to inject SSL certificates. This part is not why this issue is raised. Based on reading the code I would expect there to be a try and error message:
"Cannot find Mermaid library: %s" % javascript
I would like to also request an option to skip this check - this URL is available in the browser itself due to the way ZScaler works differently to python environment. This seems to align with the intention to just load the remote URL later with:
import mermaid from "https://unpkg.com/mermaid@10.4.0/dist/mermaid.esm.min.mjs";
I was able to reproduce the request, confirming the SSL issue is not related to this project.
https://github.com/fralau/mkdocs-mermaid2-plugin/pull/102 - Pull request for handling the exception,