diff --git a/README.md b/README.md
index 3a9daf2d2..2184745bc 100644
--- a/README.md
+++ b/README.md
@@ -548,7 +548,7 @@ Below is an illustrative directory structure to show this layout:
                 attribution.txt
 ```
 
-For an extensive example of the taxonomy layout see the [taxonomy_tree_layout](https://github.com/instructlab/taxonomy/blob/main/docs/taxonomy_diagram.png) image in the documentation folder.
+For an extensive example of this layout see, [taxonomy_tree_layout](docs/taxonomy_diagram.md) in the documentation folder.
 
 ## Contribute knowledge and skills to the taxonomy
 
diff --git a/docs/README.md b/docs/README.md
index 6e4c01bfa..134d811f1 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -2,7 +2,7 @@
 
 The purpose of these documents is to inform users and maintainers on the review/triaging process and different ways to contribute to the taxonomy repository. You can view the following:
 
-- Full layout of taxonomy repository - [Taxonomy diagram](taxonomy_diagram.png)
+- Full layout of taxonomy repository - [Taxonomy diagram](taxonomy_diagram.md)
 - Flowchart of the pull request review process - [Review process](assets/review-process.png)
 - Flowchart of how the backend works with reviewing PRS - [Backend process](assets/backend.png)
 
diff --git a/docs/taxonomy_diagram.md b/docs/taxonomy_diagram.md
new file mode 100644
index 000000000..934875088
--- /dev/null
+++ b/docs/taxonomy_diagram.md
@@ -0,0 +1,35 @@
+## Taxonomy diagram
+
+```mermaid
+ flowchart TD;
+   na[not accepting contributions\n at this time]:::na
+   taxonomy --> foundational_skill & compositional_skills & knowledge
+
+   foundational_skill:::na --> reasoning:::na
+   reasoning:::na --> common_sense_reasoning:::na
+   reasoning:::na --> mathematical_reasoning:::na
+   reasoning:::na --> theory_of_mind:::na
+
+   compositional_skills --> engineering
+   compositional_skills --> grounded
+   compositional_skills --> lingustics
+
+   grounded --> grounded/arts
+   grounded --> grounded/geography
+   grounded --> grounded/history
+   grounded --> grounded/science
+
+   knowledge --> knowledge/arts
+
+   knowledge --> knowledge/miscellaneous_unknown
+   knowledge --> knowledge/science
+   knowledge --> knowledge/technology
+   knowledge/science --> animals --> birds --> black_capped_chickadee --> black_capped_chikadee-a & black_capped_chikadee-q
+   knowledge/science --> astronomy --> constellations --> phoenix --> phoenix-a & phoenix-q
+
+   black_capped_chikadee-a{attribution.txt}
+   black_capped_chikadee-q{qna.yaml}
+   phoenix-a{attribution.txt}
+   phoenix-q{qna.yaml}
+   classDef na fill:#EEE
+```