diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index da40b853f..391183d1c 100644
--- a/.github/workflows/docs.yml
+++ b/.github/workflows/docs.yml
@@ -23,7 +23,7 @@ jobs:
           python-version: "3.10"
 
       - name: Install MkDocs and doc theme packages
-        run: pip install mkdocs mkdocs-material mkdocs-git-revision-date-localized-plugin
+        run: pip install mkdocs mkdocs-material mkdocs-git-revision-date-localized-plugin mkdocs-mermaid2-plugin
 
       - name: Build docs site
         run: mkdocs build
diff --git a/docs/build_system.md b/docs/build_system.md
index c8b8f36ea..f26bfb917 100644
--- a/docs/build_system.md
+++ b/docs/build_system.md
@@ -9,47 +9,34 @@
 !!! warning
     This page is made by someone who is not the developer and should not be considered as an official documentation of the build system. For getting the full picture, it is best to read the Makefiles and understand them yourself.
 
-## Makefile dep graph
-
-```
-Makefile                                                        
-|                                                               
-|-----  Makefile.system # !!! this is included by many of the Makefiles in the subdirectories !!!
-|       |
-|       |=====  Makefile.prebuild # This is triggered (not included) once by Makefile.system 
-|       |       |                 # and runs before any of the actual library code is built.
-|       |       |                 # (builds and runs the "getarch" tool for cpu identification,
-|       |       |                 # runs the compiler detection scripts c_check and f_check) 
-|       |       |
-|       |       -----  (Makefile.conf) [ either this or Makefile_kernel.conf is generated ] 
-|       |       |                            { Makefile.system#L243 }
-|       |       -----  (Makefile_kernel.conf) [ temporary Makefile.conf during DYNAMIC_ARCH builds ]
-|       |
-|       |-----  Makefile.rule # defaults for build options that can be given on the make command line
-|       |
-|       |-----  Makefile.$(ARCH) # architecture-specific compiler options and OpenBLAS buffer size values
-|
-|~~~~~ exports/
-|
-|~~~~~ test/
-|
-|~~~~~ utest/  
-|
-|~~~~~ ctest/
-|
-|~~~~~ cpp_thread_test/
-|
-|~~~~~ kernel/
-|
-|~~~~~ ${SUBDIRS}
-|
-|~~~~~ ${BLASDIRS}
-|
-|~~~~~ ${NETLIB_LAPACK_DIR}{,/timing,/testing/{EIG,LIN}}
-|
-|~~~~~ relapack/
+## Makefile dependency graph
+
+<!---
+An easy way to update this diagram is to copy it into https://mermaid.live
+and edit it interactively.
+-->
+
+```mermaid
+flowchart LR
+    A[Makefile] -->|included by many of the Makefiles in the subdirectories!| B(Makefile.system)
+        B -->|triggered, not included, once by Makefile.system, and runs before any of the actual library code is built. builds and runs the 'getarch' tool for cpu identification, runs the compiler detection scripts c_check/f_check| C{Makefile.prebuild}
+            C -->|either this or Makefile_kernel.conf is generated| D[Makefile.conf]
+            C -->|temporary Makefile.conf during DYNAMIC_ARCH builds| E[Makefile_kernel.conf]
+        B -->|defaults for build options that can be given on the make command line| F[Makefile.rule]
+        B -->|architecture-specific compiler options and OpenBLAS buffer size values| G[Makefile.$ARCH]
+    A --> exports
+    A -->|directories: test, ctest, utest, cpp_thread_test| H(test directories)
+    A --> I($BLASDIRS)
+        I --> interface
+        I --> driver/level2
+        I --> driver/level3
+        I --> driver/others
+    A -->|for each target in DYNAMIC_CORE if DYNAMIC_ARCH=1| kernel
+    A -->|subdirs: timing, testing, testing/EIG, testing/LIN| J($NETLIB_LAPACK_DIR)
+    A --> relapack
 ```
 
+
 ## Important Variables
 
 Most of the tunable variables are found in
diff --git a/mkdocs.yml b/mkdocs.yml
index 374b03e39..6e2b33be2 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -26,13 +26,18 @@ theme:
 
 plugins:
   - search
+  - mermaid2
   - git-revision-date-localized:
       enable_creation_date: true
 
 markdown_extensions:
   - admonition
   - pymdownx.details
-  - pymdownx.superfences
+  - pymdownx.superfences:
+      custom_fences:
+        - name: mermaid
+          class: mermaid
+          format: !!python/name:mermaid2.fence_mermaid_custom
   - footnotes
   - pymdownx.tabbed:
       alternate_style: true