Created ReSpec plugin for mermaid.js diagrams

Hi all,

Just a quick note to those authoring specifications that need diagrams (swim
lane diagrams, process flow charts, class diagrams, customer journeys, etc.).
One of the challenges of having diagrams in specifications is keeping them up
to date as the specification changes. Another challenge is ensuring that the
diagrams continue to meet a11y requirements.

As many of you already know, there is a diagramming tool called mermaid.js[1],
which let's you describe diagrams using text (similar to Markdown). The tool
then takes the text and renders a visual representation of the diagram.

I've put together an experimental plugin for (ReSpec) that enables us to embed
these text-based diagrams in our use case and specification documents. The
result is a dynamically rendered diagram that is more easily kept up to date
with the specification. In other words, you no longer need to use a separate
image/diagram editing program to create diagrams for specifications (though,
you still have that option if you want to go that route). The downside here is
that you will need to learn mermaid's markup language[1], which is fairly easy
to pick up. There is also a live editor[2] that helps you see what you've
marked up.

We've started playing around with this feature in the Verifiable Credentials
API specification:

https://github.com/w3c-ccg/vc-api/pull/286#issue-1206470583

You can read more about how to use the plugin here:

https://github.com/digitalbazaar/respec-mermaid#readme

This is the first experimental release; expect bugs[3], please report them,
and we'll fix them as soon as we can.

One thing I'll note is that Respec "export to HTML" and PR Preview is
broken... I'm guessing because in-line SVG diagrams are processed in some way
by ReSpec... seems like there is some munging going on with "notes" in
mermaid.js and ReSpec. As a result, I might have to find another block content
tag (other than PRE) to use and make sure the translation happens in ReSpec
post-processing instead of pre-processing.

Any suggestions on how to keep PRE tags untouched other than via CSS classes?
I need to preserve the mermaid.js untouched all the way through ReSpec
post-processing. Any other suggestions on how to make it better are welcome as
well.

-- manu

[1] https://mermaid-js.github.io/
[2] https://mermaid.live/
[3] https://github.com/digitalbazaar/respec-mermaid/issues

-- 
Manu Sporny - https://www.linkedin.com/in/manusporny/
Founder/CEO - Digital Bazaar, Inc.
News: Digital Bazaar Announces New Case Studies (2021)
https://www.digitalbazaar.com/

Received on Monday, 18 April 2022 15:06:46 UTC