Syntax advice for tikz diagram plugin

[dominiwe]

I need some advice after looking at other plugins that allow one to render diagrams (remark-mermaidjs, remark-smcat, remark-plantuml).

I am working on a plugin to try making it easier to render tikz diagrams, based on node-tikzjax. I am planning to implement this as follows (if my understanding is wrong, please correct me):

1. Remark parses from markdown into AST, where I then want to have a node type for my tikz diagrams.
2. Rehype goes from AST to html and that's where I need to turn the tikz nodes into SVGs.

Now, the plugins mentioned above all work by bolting their functionality on top of code blocks. E.g. one makes mermaid or smcat code blocks. But I don't like this so much because my expectance for a code block is that it displays code. I feel it's a bit of a misuse of code blocks but I would welcome discussion about that.

What I'd like to do instead is to give the user the option to either do it the code block way or to use custom blocks as provided by remark-directive. I think that's better too because it makes things configurable for the user. So my real question is, is it a good idea to "depend" on the remark-directive plugin and that needing to be at an earlier step in the pipeline? How would I declare this or make it easy to understand for a user? Any advice is welcome here.

[remcohaszing]

Don’t create a remark plugin for this. Create a rehype plugin instead. I recommend to have a look at rehype-mermaid

You can’t really use directives for this. Content between directives are markdown and will be parsed as such. I investigated this for rehype-mermaid, because some platforms use a directive-like syntax for Mermaid diagrams.

Your point about code blocks being for code is fair, but code blocks are also your only real option. Markdown code blocks support metadata. You could leverage that.

```language Everything after the language followed by a space is meta
Your code
```

So the syntax could be something like:

```tikz render
Diagram code
```

This meta is available on the <code> or <pre> element. I don’t recall which one. The language is available as the language-tikz node on the <code> element.

[dominiwe]

Thank you for the reply! I was thinking of following the workspace structure of remarkjs/remark-math and just creating the package rehype-tikz in the workspace. Following that projects structure helps me as a newcomer, also when it comes to tests etc.. If I change my mind in the future regarding syntax or adding a custom node type, I'll still have the flexibility of also adding a remark-tikz package then.

I'll follow your advice concerning code blocks, I didn't think hard enough to remember that the content between directives will be parsed as markdown.

And thank you for making rehype-mermaid, it helps me a lot!

[remcohaszing]

Don’t make a remark-tikz package. You really only need the rehype plugin.

[dominiwe]

I now started two projects based on both rehype-mermaid and mermaid-isomorphic (basically tikz equivalents of these) and have a working poc locally.
But since I have never made an open source contribution I am a bit confused when it comes to licensing. Given that I took your projects as starting points I'd have to license it under the MIT license. But I think I would also need the LPPL license for the latex bits... do you have any advice regarding that?

[wooorm]

If you use the package node-tikzjax then you don’t. If you read that source and “derive” your work from it, then you do, indeed.

[remcohaszing]

Yes, licensing can be confusing. Most developers aren’t lawyers and don’t know the exact rules. (Neither do I!) Ask 10 the people the same question, and you’ll get 10 different answers. In general:

• You can use the license you like. The MIT license is generally a good default.
• You don’t need to include a license for the languages you write (LaTeX or JavaScript).
• You don’t need to include a license for the dependencies you use (node-tikzjax).
• You don’t need to worry about licensing if you copy a simple line of code.
• If you base your code on other code, it’s nice to give some attribution to the original author. For example, this can be a link to a GitHub project or StackOverflow answer in a comment or in the readme. Besides attribution being nice, it may also be useful to know where the code originates from.
• If people see you tried to do the right thing, they won’t make a big deal out of it.
• I have taken over maintenance of some open source projects. In that case I keep the original license.

So if I were you, I would just add the MIT license with your own name and not worry about it. And if it feels right to you, you can give attribution where it makes sense to you.