Use the `enable_uml` Feature #146

RoyiAvital · 2022-05-21T15:08:09Z

RoyiAvital
May 21, 2022

In a MarkDown document I use created the following frontmatter:

---
    # Meta Data
    Title: Some Title
    Summary: Few Words
    Author:
        - Royi

    # Settings
    settings:
        enable_uml: true
        image_path_conversion: base64
        markdown_extensions:
          - markdown.extensions.footnotes
          - markdown.extensions.fenced_code
          - markdown.extensions.tables
          - markdown.extensions.admonition
          - markdown.extensions.md_in_html
          - markdown.extensions.toc:
                title: Table of Contents
                toc_depth: 2-3
          - pymdownx.arithmatex:
                generic: true
                smart_dollar: false
        allow_css_overrides: true
---

In my Markdown Preview settings I defined:

{
    "js": {
        "markdown": [
            "https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.9/MathJax.js",
            "res://MarkdownPreview/js/math_config.js",
            // Required libraries to transform UML notation
            "https://cdnjs.cloudflare.com/ajax/libs/raphael/2.2.7/raphael.min.js",
            "https://cdnjs.cloudflare.com/ajax/libs/underscore.js/1.8.3/underscore-min.js",
            "https://cdnjs.cloudflare.com/ajax/libs/js-sequence-diagrams/1.0.6/sequence-diagram-min.js",
            "https://cdnjs.cloudflare.com/ajax/libs/flowchart/1.6.5/flowchart.min.js",

            // This library applies the above libraries to the fenced code blocks `flow` and `sequence`.
            "res://MarkdownPreview/js/uml.js",
        ]
    },

I did that by following UML Support.

The generated HTML has:

<html>
<body>
<!--StartFragment-->

</script><script type='text/javascript' src='https://cdnjs.cloudflare.com/ajax/libs/raphael/2.2.7/raphael.min.js'></script><script type='text/javascript' src='https://cdnjs.cloudflare.com/ajax/libs/underscore.js/1.8.3/underscore-min.js'></script><script type='text/javascript' src='https://cdnjs.cloudflare.com/ajax/libs/js-sequence-diagrams/1.0.6/sequence-diagram-min.js'></script><script type='text/javascript' src='https://cdnjs.cloudflare.com/ajax/libs/flowchart/1.6.5/flowchart.min.js'></script><script>(function () {
--
  | 'use strict';
  |  
  | /**
  | * Targets special code or div blocks and converts them to UML.
  | * @param {object} converter is the object that transforms the text to UML.
  | * @param {string} className is the name of the class to target.
  | * @param {object} settings is the settings for converter.
  | * @return {void}
  | */
  | var uml = (function (converter, className, settings) {
  |  
  | var getFromCode = function getFromCode(parent) {
  | // Handles `<pre><code>`
  | var text = "";
  | for (var j = 0; j < parent.childNodes.length; j++) {
  | var subEl = parent.childNodes[j];
  | if (subEl.tagName.toLowerCase() === "code") {
  | for (var k = 0; k < subEl.childNodes.length; k++) {
  | var child = subEl.childNodes[k];
  | var whitespace = /^\s*$/;
  | if (child.nodeName === "#text" && !whitespace.test(child.nodeValue)) {
  | text = child.nodeValue;
  | break;
  | }
  | }
  | }
  | }
  | return text;
  | };
  |  
  | var getFromDiv = function getFromDiv(parent) {
  | // Handles `<div>``
  | return parent.textContent \|\| parent.innerText;
  | };
  |  
  | // Change article to whatever element your main Markdown content lives.
  | var article = document.querySelectorAll("article");
  | var blocks = document.querySelectorAll("pre." + className + ",div." + className
  |  
  | // Is there a settings object?
  | );var config = settings === void 0 ? {} : settings;
  |  
  | // Find the UML source element and get the text
  | for (var i = 0; i < blocks.length; i++) {
  | var parentEl = blocks[i];
  | var el = document.createElement("div");
  | el.className = className;
  | el.style.visibility = "hidden";
  | el.style.position = "absolute";
  |  
  | var text = parentEl.tagName.toLowerCase() === "pre" ? getFromCode(parentEl) : getFromDiv(parentEl
  |  
  | // Insert our new div at the end of our content to get general
  | // typeset and page sizes as our parent might be `display:none`
  | // keeping us from getting the right sizes for our SVG.
  | // Our new div will be hidden via "visibility" and take no space
  | // via `position: absolute`. When we are all done, use the
  | // original node as a reference to insert our SVG back
  | // into the proper place, and then make our SVG visible again.
  | // Lastly, clean up the old node.
  | );
  | article[0].appendChild(el);
  | var diagram = converter.parse(text);
  | diagram.drawSVG(el, config);
  | el.style.visibility = "visible";
  | el.style.position = "static";
  | parentEl.parentNode.insertBefore(el, parentEl);
  | parentEl.parentNode.removeChild(parentEl);
  | }
  | });
  |  
  | (function () {
  | var onReady = function onReady(fn) {
  | if (document.addEventListener) {
  | document.addEventListener("DOMContentLoaded", fn);
  | } else {
  | document.attachEvent("onreadystatechange", function () {
  | if (document.readyState === "interactive") {
  | fn();
  | }
  | });
  | }
  | };
  |  
  | onReady(function () {
  | if (typeof flowchart !== "undefined") {
  | uml(flowchart, "uml-flowchart");
  | }
  |  
  | if (typeof Diagram !== "undefined") {
  | uml(Diagram, "uml-sequence-diagram", { theme: "simple" });
  | }
  | });
  | })();
  |  
  | }());
  | </script>

<!--EndFragment-->
</body>
</html>

The MarkDown text (The example in flow-charts.js):

\```flow
st=>start: Start:>http://www.google.com[blank]
e=>end:>http://www.google.com
op1=>operation: My Operation
sub1=>subroutine: My Subroutine
cond=>condition: Yes
or No?:>http://www.google.com
io=>inputoutput: catch something...
para=>parallel: parallel tasks

st->op1->cond
cond(yes)->io->e
cond(no)->para
para(path1, bottom)->sub1(right)->op1
para(path2, top)->op1
\```

Generated this HTML:

<html>
<body>
<!--StartFragment-->

<pre><code class="flow">st=&gt;start: Start:&gt;http://www.google.com[blank]
--
  | e=&gt;end:&gt;http://www.google.com
  | op1=&gt;operation: My Operation
  | sub1=&gt;subroutine: My Subroutine
  | cond=&gt;condition: Yes
  | or No?:&gt;http://www.google.com
  | io=&gt;inputoutput: catch something...
  | para=&gt;parallel: parallel tasks
  |  
  | st-&gt;op1-&gt;cond
  | cond(yes)-&gt;io-&gt;e
  | cond(no)-&gt;para
  | para(path1, bottom)-&gt;sub1(right)-&gt;op1
  | para(path2, top)-&gt;op1
  | </code></pre>

<!--EndFragment-->
</body>
</html>

Yet nothing is rendered.

What am I doing wrong?

Answered by facelessuser

May 24, 2022

Unfortunately, this discussion had a bunch of different topics and not a specific, definitive post that answered the question.

Title case issue is fixed on master and will be available in the next release.
UML support does work, but the enable_uml option was from old legacy behavior and the reference has been removed from the documentation.
Mermaid support is added on master and will be available in the next release.

View full answer

facelessuser · 2022-05-21T15:16:39Z

facelessuser
May 21, 2022
Maintainer

I don't have an answer yet, but it may be due to the fact that you are indenting your frontmatter when you don't need to, but I haven't run through your example yet.

8 replies

facelessuser May 21, 2022
Maintainer

If that works, you should be able to move the JS to your settings file. If you add unsupported syntax to the flow block, it may break.

Also, don't use fenced_code use pymdownx.superfences.

RoyiAvital May 21, 2022
Author

But what you did is creating a custom fence with pymdownx.superfences. But according to documentation one could have that without enable_uml.
Moreover, by documentation, if one only use Markdown Preview with enable_uml and flow things should work without any pymdownx extension, right?

So basically I don't understand the role of enable_uml in your front matter.

facelessuser May 21, 2022
Maintainer

Honestly, the documentation doesn't talk about enable_uml. I think there is one example of settings that shows it, but there is no code to actually process it. I think it was an old legacy thing that I simply forgot to remove from a few examples.

RoyiAvital May 21, 2022
Author

OK. So I think it is better to remove all the UML Support from MarkdownPreview or maybe just refer to the extension as an option.
Because for that matter, nothing special about flow and sequence, enabling them is just like enabling mermaid for that matter.

By the way, I thought the title and summary sections will have some effect on the page when loaded on the browser (Like the tool tip of the tab and the title of the tab) but they don't.
Any way to change the Favicon, Title of the Tab and the Tool Tip?

For instance <title>FileName</title> is populated by the file name and not the title field.

facelessuser May 21, 2022
Maintainer

OK. So I think it is better to remove all the UML Support from MarkdownPreview or maybe just refer to the extension as an option.

There's not really UML support code or anything in the codebase at this point. We simply define some custom fences by default, and if people want to use them, they add the JS. I mean, I guess we have a super simple loader written in JS, but that's it.

TBH, the default libraries used for flow and sequence, I don't even think they are well supported naymore.

It's mainly kept for legacy purposes. At one point, it was more integrated, but I've worked to make things less specialized and more generic moving forward. If someone wants to create UMLs with some other special library, they can use a custom fence as that is now how they all are done.

It is certainly possible that we could have a big major revision that simply provides the Mermaid loader and ditches the old loader.

By the way, I thought the title and summary sections will have some effect on the page when loaded on the browser (Like the tool tip of the tab and the title of the tab) but they don't.

title is controlled with frontmatter:

---
title: Test Page
---

That seems to work for me. I have nothing that currently handles summary or favicon. As this was primarily just used to preview Markdown, these weren't really a big concern. That's not saying we couldn't add support for them.

RoyiAvital · 2022-05-22T05:23:32Z

RoyiAvital
May 22, 2022
Author

I totally agree on the generic path. Hence I think you should, at the moment, update the documentation as the impression I got from it is that I can have some UML support using MarkDown Preview by itself.

Regarding the title, see my front matter, I use it, yet it doesn't change the <title> </title> tag of the generated HTML. It only generates a meta tag with the title.

4 replies

facelessuser May 22, 2022
Maintainer

It does change the title.

When the meta extension is enabled (https://python-markdown.github.io/extensions/meta_data), the results will be written to the HTML head in the form <meta name="key" content="value1,value2">. title is the one exception, and its content will be written to the title tag in the HTML head.

Title =/= title. I'd try lowercase.

facelessuser May 22, 2022
Maintainer

I totally agree on the generic path. Hence I think you should, at the moment, update the documentation as the impression I got from it is that I can have some UML support using MarkDown Preview by itself.

I do plan to fix it. I'd maybe open up a specific issue so it doesn't get forgotten. I maintain a lot of repos, so I can often forget things if they aren't tracked.

RoyiAvital May 22, 2022
Author

I opened an issue on #147.

facelessuser May 22, 2022
Maintainer

I think I was more specifically responding to the UML documentation part as far as issues go. Pretty much all the recognized frontmatter keys are lowercase and case-sensitive. They've always been that way. I guess these are metadata though, so I'll consider possibly changing them, but if we do, only metadata tags would be case insensitive, not settings keys.

facelessuser · 2022-05-24T01:25:50Z

facelessuser
May 24, 2022
Maintainer

Unfortunately, this discussion had a bunch of different topics and not a specific, definitive post that answered the question.

Title case issue is fixed on master and will be available in the next release.
UML support does work, but the enable_uml option was from old legacy behavior and the reference has been removed from the documentation.
Mermaid support is added on master and will be available in the next release.

0 replies

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Use the `enable_uml` Feature #146

{{title}}

Replies: 3 comments 12 replies

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

{{title}}

Select a reply

Use the enable_uml Feature #146

RoyiAvital May 21, 2022

Replies: 3 comments · 12 replies

facelessuser May 21, 2022 Maintainer

facelessuser May 21, 2022 Maintainer

RoyiAvital May 21, 2022 Author

facelessuser May 21, 2022 Maintainer

RoyiAvital May 21, 2022 Author

facelessuser May 21, 2022 Maintainer

RoyiAvital May 22, 2022 Author

facelessuser May 22, 2022 Maintainer

facelessuser May 22, 2022 Maintainer

RoyiAvital May 22, 2022 Author

facelessuser May 22, 2022 Maintainer

facelessuser May 24, 2022 Maintainer

Use the `enable_uml` Feature #146

RoyiAvital
May 21, 2022

Replies: 3 comments 12 replies

facelessuser
May 21, 2022
Maintainer

facelessuser May 21, 2022
Maintainer

RoyiAvital May 21, 2022
Author

facelessuser May 21, 2022
Maintainer

RoyiAvital May 21, 2022
Author

facelessuser May 21, 2022
Maintainer

RoyiAvital
May 22, 2022
Author

facelessuser May 22, 2022
Maintainer

facelessuser May 22, 2022
Maintainer

RoyiAvital May 22, 2022
Author

facelessuser May 22, 2022
Maintainer

facelessuser
May 24, 2022
Maintainer