Skip to content

Graphviz-superfence

What is that ?

This project aims to convert Graphviz code to svg images when integrated to markdown documents, for example on this mkdocs-material website where it can automatically adapt to dark/light theme.

It is based on pymdown-extensions superfences and an operational graphviz installation.

Here is a demo

g ListeAmén ListeAmén cid : varchar amid : varchar Aménagement Aménagement amid : varchar Amén : varchar ListeAmén:w->Aménagement:w Candidat Candidat cid : varchar nom : varchar prénom : varchar genre : char(1) âge : varchar adresse : varchar profession : varchar diplôme : varchar ListeAmén->Candidat ListeAmén:e->Candidat:w AgrégExtInfo AgrégExtInfo cid : varchar aid : varchar ep : char(1) Candidat->AgrégExtInfo AgrégExtInfo:w->Candidat:e Académie Académie aid : varchar nom : varchar AgrégExtInfo->Académie AgrégExtInfo:e->Académie:w CapesNSI CapesNSI cid : varchar aid : varchar CapesNSI:w->Candidat:e CapesNSI:e->Académie:w 

```dot
digraph g {
    rankdir=LR

    node [shape=plaintext, margin=0, fontname="roboto"];

ListeAmén [
label = <
<TABLE BORDER="0" CELLBORDER="1" CELLSPACING="0">
  <TH><TD BGCOLOR="grey"><B>ListeAmén</B></TD></TH>
  <TR><TD PORT="cid"><B><I>cid</I> : varchar</B></TD></TR>
  <TR><TD PORT="amid"><B><I>amid</I> : varchar</B></TD></TR>
</TABLE>>
];
Aménagement [
label = <
<TABLE BORDER="0" CELLBORDER="1" CELLSPACING="0">
  <TH><TD BGCOLOR="grey"><B>Aménagement</B></TD></TH>
  <TR><TD PORT="amid"><B><I>amid</I> : varchar</B></TD></TR>
  <TR><TD> Amén : varchar</TD></TR>
</TABLE>>
];

Candidat [
label = <
<TABLE BORDER="0" CELLBORDER="1" CELLSPACING="0">
  <TH><TD BGCOLOR="grey"><B>Candidat</B></TD></TH>
  <TR><TD PORT="cid"><B>cid : varchar</B></TD></TR>
  <TR><TD> nom : varchar</TD></TR>
  <TR><TD> prénom : varchar</TD></TR>
  <TR><TD> genre : char(1)</TD></TR>
  <TR><TD> âge : varchar</TD></TR>
  <TR><TD> adresse : varchar</TD></TR>
  <TR><TD> profession : varchar</TD></TR>
  <TR><TD> diplôme : varchar</TD></TR>

</TABLE>>
];

AgrégExtInfo [
label = <
<TABLE BORDER="0" CELLBORDER="1" CELLSPACING="0">
  <TH><TD BGCOLOR="grey"><B>AgrégExtInfo</B></TD></TH>
  <TR><TD PORT="cid"><B><I>cid</I> : varchar</B></TD></TR>
  <TR><TD PORT="aid"><I>aid</I> : varchar</TD></TR>
  <TR><TD> ep : char(1)</TD></TR>
</TABLE>
>
];

CapesNSI [
label = <
<TABLE BORDER="0" CELLBORDER="1" CELLSPACING="0">
  <TH><TD BGCOLOR="grey"><B>CapesNSI</B></TD></TH>
  <TR><TD PORT="cid"><B><I>cid</I> : varchar</B></TD></TR>
  <TR><TD PORT="aid"><I>aid</I> : varchar</TD></TR>
</TABLE>>
];

Académie [
label = <
<TABLE BORDER="0" CELLBORDER="1" CELLSPACING="0">
  <TH><TD BGCOLOR="grey"><B>Académie</B></TD></TH>
  <TR><TD PORT="aid"><B>aid : varchar</B></TD></TR>
  <TR><TD> nom : varchar</TD></TR>
</TABLE>>
];

ListeAmén -> Candidat -> AgrégExtInfo -> Académie [color=none, weight=100];
{ rank = same; ListeAmén; Aménagement; }
{ rank = same; AgrégExtInfo; CapesNSI;}
ListeAmén:amid:w -> Aménagement:amid:w;
ListeAmén:cid:e -> Candidat:cid:w;
AgrégExtInfo:cid:w -> Candidat:cid:e;
CapesNSI:cid:w -> Candidat:cid:e;
AgrégExtInfo:aid:e -> Académie:aid:w;
CapesNSI:aid:e -> Académie:aid:w;
}

```

Install it...

graphviz-superfence is a custom formatter used by pymdown-extensions on mkdocs-material theme... so to use it :

Installation
pip install graphviz-superfence
sudo apt install graphviz

Configure Mkdocs material

A minimal configuration could be this one :

mkdocs.yml
site_name: Mkdocs-latex
theme:
  name: material #Need to install mkdocs-material
  palette: 
    # Palette toggle for light mode
    - scheme: default
      toggle:
        icon: material/brightness-7 
        name: Switch to dark mode
    # Palette toggle for dark mode
    - scheme: slate
      toggle:
        icon: material/brightness-4
        name: Switch to light mode

markdown_extensions:
  - pymdownx.superfences:
        custom_fences:
        - name: dot
          class: dot
          format: !!python/object/apply:graphviz_superfence.formatter
            kwds:
              white: var(--md-typeset-color) # Replacement of white colors for dynamic light/dark mode
              # Transparent background
              Gbgcolor: none    # Background colors
              # Then everything we need to set to white
              Gcolor: white     # Graph color
              Gfontcolor: white # Graph font color              
              Ncolor: white     # Node color                   
              Nfontcolor: white # Node font color
              Ecolor: white     # Edge color                 
              Efontcolor: white # Edge font color
          validator: !!python/name:graphviz_superfence.validator

Use it

  • Graphviz fences are either opened by ```dot or ```{.dot}

  • You can replace any svg colors with customs one, which is usefull for setting variable colors (ex. var(--md-typeset-color)) that will adapt whith mkdocs light/dark mode.

  • You can set any attributes like you would do with graphviz command line

  • This can be done inline (ex. ```{.dot Nfontcolor="red" red="var(--md-default-bg-color)"}), or globally in mkdocs.yml (see above).

  • In order to display it correctly on mkdocs-material, use roboto fonts (ex. Nfontname="roboto") because those comes with matrerial theme.