W3C home > Mailing lists > Public > public-credentials@w3.org > April 2022

Added support for mermaid.js diagrams in ReSpec

From: Manu Sporny <msporny@digitalbazaar.com>
Date: Mon, 18 Apr 2022 10:28:13 -0400
To: W3C Credentials CG <public-credentials@w3.org>
Message-ID: <74c55b28-cd0e-c0b2-ef0b-9507f837d167@digitalbazaar.com>
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 be accessible.

There are usually a fair number of diagrams in CCG use cases documents as well
as specifications.

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 a plugin for our specification authoring environment
(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 VC 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.

-- 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 14:28:29 UTC

This archive was generated by hypermail 2.4.0 : Monday, 18 April 2022 14:28:30 UTC