Skip to content

Render Mermaid diagram in MkDocs using …|as('mermaid') filter

Context

We have a YAML-LD file, called yaml-ld.yamlld, in our Mkdocs directory. We need to render it as a Mermaid diagram and insert into a page using mkdocs-macros-plugin. What syntax should we use?

Customization

If we are going to do any customization of the diagram, we will do that in YAML-LD, not in the page itself.

Alternatives

{{ "yaml-ld.yamlld"|as('mermaid') }}

➕ Pro

  • Still simple syntax
  • Is reusable in other contexts

➖ Contra

  • Might be more complicated to use 
{{ mermaid("yaml-ld.yamlld") }}

➕ Pro

  • Simple syntax

➖ Contra

  • No control over the diagram
  • Necessity to invent a new function for each new visualization beyond Mermaid 
{{ "yaml-ld.yamlld"|mermaid }}

➕ Pro

  • Simple syntax

➖ Contra

  • No control over the diagram
  • Necessity to invent a new filter for each new visualization beyond Mermaid

Example

graph LR
  https___json-ld_github_io_yaml-ld_spec("YAML-LD")
  click https___json-ld_github_io_yaml-ld_spec "https://json-ld.github.io/yaml-ld/spec/"
  Literal-5cc294277266dd585fb000bcc3b0dc5d[["A set of conventions built on top of YAML, which outlines how to serialize
  Linked Data as YAML based on JSON-LD syntax, semantics, and APIs.
  "]]
  https___json-ld_github_io_yaml-ld_spec("YAML-LD")
  click https___json-ld_github_io_yaml-ld_spec "https://json-ld.github.io/yaml-ld/spec/"
  https___w3id_org_fair_fip_terms_Knowledge-representation-language("Knowledge representation language")
  click https___w3id_org_fair_fip_terms_Knowledge-representation-language "https://w3id.org/fair/fip/terms/Knowledge-representation-language"
  https___json-ld_github_io_yaml-ld_spec --- 3239c953eb87d0b03a2fae81ce05668e(["Description"])--> Literal-5cc294277266dd585fb000bcc3b0dc5d
  click 3239c953eb87d0b03a2fae81ce05668e "http://purl.org/dc/terms/description"
  class 3239c953eb87d0b03a2fae81ce05668e predicate
  https___json-ld_github_io_yaml-ld_spec --- 3ab0fa2629c4b676a83340de197d8760(["type"])--> https___w3id_org_fair_fip_terms_Knowledge-representation-language
  click 3ab0fa2629c4b676a83340de197d8760 "http://www.w3.org/1999/02/22-rdf-syntax-ns#type"
  class 3ab0fa2629c4b676a83340de197d8760 predicate
  classDef predicate fill:transparent,stroke:transparent,stroke-width:0px;