diff --git a/markdown_utils.py b/markdown_utils.py
new file mode 100644
index 0000000..33b6a29
--- /dev/null
+++ b/markdown_utils.py
@@ -0,0 +1,17 @@
+import mistune
+from mistune.renderers.markdown import MarkdownRenderer
+
+
+class HeadingsRenderer(MarkdownRenderer):
+    def __init__(self, min_level: int):
+        super().__init__()
+        self.min_level = min_level
+
+    def heading(self, token, state):
+        token["attrs"]["level"] += self.min_level - 1
+        return super().heading(token, state)
+
+
+def limit_markdown_headings(source: str, min_level: int) -> str:
+    markdown = mistune.create_markdown(renderer=HeadingsRenderer(min_level))
+    return markdown(source)
diff --git a/project.py b/project.py
index 89431cb..eefb777 100644
--- a/project.py
+++ b/project.py
@@ -11,6 +11,7 @@ import json
 import git_utils
 import git
 import shutil
+from markdown_utils import limit_markdown_headings
 
 CELL_URL = 'https://skywater-pdk.readthedocs.io/en/main/contents/libraries/sky130_fd_sc_hd/cells/'
 
@@ -192,6 +193,9 @@ class Project():
         docs = self.yaml['documentation']
         docs['project_type'] = self.get_project_type_string()
         docs['git_url'] = self.git_url
+        # "How it works" and "How to test" may include markdown headings - make sure they don't break the ToC
+        docs['how_it_works'] = limit_markdown_headings(docs['how_it_works'], min_level=4)
+        docs['how_to_test'] = limit_markdown_headings(docs['how_to_test'], min_level=4)
         return docs
 
     def get_wokwi_url(self):
diff --git a/requirements.txt b/requirements.txt
index 9ce815a..153b9fc 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -12,6 +12,7 @@ gitdb==4.0.10
 GitPython==3.1.31
 idna==3.4
 importlib-resources==5.12.0
+mistune==3.0.1
 numpy==1.24.3
 Pillow==9.5.0
 pycparser==2.21