Creating diagrams with Mermaid
Published on 28 April 2022 by Andrew Owen (4 minutes)
I’m a convert to writing docs in Markdown. Most of this website is written using it (displayed with Hugo). But sometimes you need to include a chart or diagram in your docs.
Historically, this would likely have been in the form of an image file, exported from Microsoft Visio. Which is fine until you need to update the chart. At which point you had to find the source file, open it, edit it, export an updated image, and upload it to your website.
There’s a better way, and it’s called Mermaid. It’s a JavaScript based tool for creating charts and diagrams using a Markdown-inspired syntax. At the end of this article, I’ve included an example in context: an overview of Proof Key for Code Exchange (PKCE). Here’s the code that generates the image:
sequenceDiagram
participant User
participant Mobile App
participant STS
participant API
User->>Mobile App: 1. Click login link.
loop challenge
Mobile App->Mobile App: 2. Generate code verifier and code challenge.
end
Mobile App->>STS: 3. Authorization code request and code challenge to authorize.
STS->>User: 4. Redirect to login/authorization prompt.
User->>STS: 5. Authenticate and consent
STS->>Mobile App: 6. Authorize code.
Mobile App->>STS: 7. Authorization code and code verified to OAuth token.
loop validate
STS->STS: 8. Validate code verifier and challenge.
end
STS->>User: 9. ID token and access token.
User->>API: 10. Request user data with access token.
API->>User: 11. Response.
But before you can use Mermaid, you need to add it to your website. There’s a beginner’s guide, but as I’m using the Hugo static site generator for this website, I’ll explain how I added Mermaid to Hugo. It’s super easy.
First, grab the latest version and put the files in your Git repository in the /static/mermaid/ path.
Second, create a file in your Git repository with the path /layouts/shortcodes/mermaid.html containing:
<link href="{{ "mermaid/mermaid.css" | relURL }}" type="text/css" rel="stylesheet"/>
<script defer src="{{ "mermaid/mermaid.js" | relURL }}">mermaid.initialize({startOnLoad:true});</script>
<div class="mermaid" align="{{ if .Get "align" }}{{ .Get "align" }}{{ else }}center{{ end }}" >{{ safeHTML .Inner }}</div>
This creates a Hugo shortcode that enables you to use Mermaid on any page. And that’s it. You can now include Mermaid in your markdown. There are plug-ins for VSCode to display Mermaid, but if you’re using a headless CMS, then the easiest way to create your charts is in the live editor.
OAuth 2.0 public clients using the authorization code flow are susceptible to authorization code interception attack. You can mitigate against this by using a Proof Key for Code Exchange (PKCE as defined in OAuth 2.0 RFC 7636).
PKCE enables you to prevent malicious use of a custom URL scheme to capture redirects (for example MyApp://) that could potentially allow applications to receive an authorization code from your authorization server.
The PKCE authorization code flow adds a secret (a code_verifier generated using SHA-256) created by the client application that’s verified by the authorization server. The client application creates a transform value (hash string) of the code_verifier called the code_challenge which is sent using HTTPS to retrieve an authorization code. A malicious attacker can intercept this code, but can’t exchange it for a token without the code_verifier.
The PKCE authorization code flow is similar to the standard authorization code flow. It uses a Secure Token Service (STS).
code_verifier and uses it to generate code_challenge.code_challenge.code_challenge and redirects user to client with authorization code.code and code_verifier to STS.code_challenge and code_verifier.