📈 My Site API shown via Mermaid
19 Apr, 2020I recently learned about mermaid.js, a library for declarative charts that’s Markdown-friendly. I wanted to play with it, so here we are.
While it is still a JS library, I don’t have to write any special JS to use it; all I had to do was load the library and make a couple <div>
s on the page.
Currently, I’m using a Hugo shortcode I wrote to declare that <div>
(since I’m making it a practice to avoid inline HTML in Markdown), but I’m hoping that soon we may see support for render templates for code blocks and eventually Markdown adding code block syntax for rendering because I want to avoid being tied to a specific library as well.
Let’s make some charts
Here’s a couple simple Pie charts with stats I pulled from the JSON-LD/Schema.org-based API I added to my sites recently, along with their code :
pie title Content Distribution by Site
"Blog" : 36
"Visualizations" : 6
"Food" : 5
"Photos" : 1
Pretty easy, right? Here’s another:
Vega
After I learned about mermaid, I was doing a little research and found out that there’s another library called Vega-Lite, which has a very similar premise but is based more on data charting than diagrams. TL;DR, Vega was easy to throw in as well, so here’s a demo. Vega-Lite uses a JSON object to declare its data, unlike Mermaid, which uses a text notation.
Here are the same charts as above, but in Vega:
Code for the left/first, based on this example, but with a tooltip added:
{
"$schema": "https://vega.github.io/schema/vega-lite/v4.json",
"description": "Pie chart of content by site",
"data": {
"values": [
{"category": "Blog", "value": 36},
{"category": "Visualizations", "value": 6},
{"category": "Food", "value": 5},
{"category": "Photos", "value": 1}
]
},
"mark": {"type": "arc", "tooltip": true},
"encoding": {
"theta": {"field": "value", "type": "quantitative"},
"color": {"field": "category", "type": "nominal"}
},
"view": {"stroke": null}
}
It’s a lot longer to write, but Vega-Lite is prettier/more user-friendly, more powerful, has a lot more support for chart types, and is used by many large companies.
More Mermaid
Here are a few more visualizations of creating the API and the search engine based on it. I’m using Mermaid for these since I want diagrams and Vega-Lite doesn’t have those.
Here’s what I currently provide for Schema output from the root API call.
Note that WebPage
as mainEntityOfPage
is the same Schema @type
as the WebPage
class, but has different properties given.
Most values are strings because of how they’re expected to be encoded.
The Schema relationships are also visible here, so you can see how ImageGallery
is a child of WebPage
, but BlogPosting
and Recipe
have to define their relationship explicitly (note that Schema says any web page is implicitly a WebPage
, but this isn’t always respected).
Here’s a snippet of that:
classDiagram
Array *-- WebSite
class Array
class WebSite{
+String url
}
Here’s a diagram of what learning the Schema API syntax looked like. A lot of the confusion is because there are multiple correct ways to write Schema and Google implements its own variant of Schema that doesn’t technically contradict Schema per say but does have its own nuances. Most of the time was spent learning the syntax as opposed to writing code.
Sorry if this goes off-page…
Here’s what the API looks like:
One final example, how my sites are deployed:
So yeah, Mermaid is pretty powerful for diagrams. The state diagram also demonstrated that it has some room for refinement, but regardless I’m really happy about what this enables me to do.