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_5cc294277266[["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___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 --- Edge_657f943e6831(["Description"])--> Literal_5cc294277266
  click Edge_657f943e6831 "http://purl.org/dc/terms/description"
  https___json_ld_github_io_yaml_ld_spec --- Edge_4d5e0cf0ff5b(["∈ type"])--> https___w3id_org_fair_fip_terms_Knowledge_representation_language
  click Edge_4d5e0cf0ff5b "http://www.w3.org/1999/02/22-rdf-syntax-ns#type"
  classDef predicate fill:#1f2233,stroke:transparent,color:#f8fafc,stroke-width:0px;
  classDef hidden fill:transparent,stroke:transparent,color:transparent,stroke-width:0px;
  classDef nanopubdot fill:#0f172a,stroke:#0f172a,color:transparent,stroke-width:2px;
  classDef transparent fill:transparent,stroke:transparent,color:transparent,stroke-width:0px;
  class Edge_657f943e6831,Edge_4d5e0cf0ff5b predicate