Ignore README headings inside code blocks

repodx.py

@@ -112,8 +112,18 @@ def check_gitignore(repo_path):
 
 def markdown_headings(markdown_text):
     headings = []
+    inside_fenced_code_block = False
 
     for line in markdown_text.splitlines():
+        stripped_line = line.strip()
+
+        if stripped_line.startswith("```") or stripped_line.startswith("~~~"):
+            inside_fenced_code_block = not inside_fenced_code_block
+            continue
+
+        if inside_fenced_code_block:
+            continue
+
         match = re.match(r"^\s{0,3}#{1,6}\s+(.+?)\s*$", line)
 
         if match:

tests/test_repodx.py

@@ -235,6 +235,45 @@ def test_check_readme_reports_unreadable_file(self):
         self.assertEqual(len(result), 1)
         self.assertTrue(result[0].startswith("Could not read README.md:"))
 
+    def test_check_readme_ignores_heading_like_lines_inside_code_blocks(self):
+        with tempfile.TemporaryDirectory() as temp_dir:
+            repo_path = Path(temp_dir)
+            (repo_path / "README.md").write_text(
+                "# Project\n\n"
+                "```python\n"
+                "# Installation\n"
+                "# Usage\n"
+                "```\n",
+                encoding="utf-8",
+            )
+
+            result = repodx.check_readme(repo_path)
+
+            self.assertEqual(
+                result,
+                [
+                    "Missing README heading: Installation",
+                    "Missing README heading: Usage",
+                ],
+            )
+
+    def test_check_readme_accepts_real_headings_around_code_blocks(self):
+        with tempfile.TemporaryDirectory() as temp_dir:
+            repo_path = Path(temp_dir)
+            (repo_path / "README.md").write_text(
+                "# Project\n\n"
+                "## Installation\n\n"
+                "```python\n"
+                "# Not a heading\n"
+                "```\n\n"
+                "## Usage\n",
+                encoding="utf-8",
+            )
+
+            result = repodx.check_readme(repo_path)
+
+            self.assertEqual(result, [])
+
     def test_check_readme_reports_os_error(self):
         with tempfile.TemporaryDirectory() as temp_dir:
             repo_path = Path(temp_dir)