Guide: Diagnosing & Fixing Malformed Markdown Links in Knowledge Bases

This guide explains how to identify, repair, and prevent malformed Markdown links across curriculum knowledge bases (such as SurrealDB, PostgreSQL, MongoDB, CSS, React, etc.).

---

1. The Problem: Understanding Malformed Link Syntax

When generating technical documentation, AI models or automated scripts sometimes concatenate parenthetical file paths inside the link label brackets [...] instead of placing them outside in the link target parentheses (...).

Common Broken Link Patterns

The Correct Markdown Link Pattern

- [Link Title](relative/path/to/file.md) — Description

• Link Title ([...]): Contains only the human-readable term name or code symbol (e.g. [Array Type] or [string Type]).
• Target URL ((...)): Placed immediately after ], containing only the relative file path (e.g. (../level_02/array_type.md)).
• Separator & Description: Follows the link token cleanly (e.g. — Description).

---

2. Automated Fix Tool (fix_markdown_links.js)

A dedicated repair utility script is stored at knowledge-base/fix_markdown_links.js.

How to Run the Script

Option A: Scan and Fix ALL Knowledge Bases

To repair all curriculum directories (01-html, 02-css, 12-postgres, 13-mongodb, 14-surrealdb, etc.):

node knowledge-base/fix_markdown_links.js --all

Option B: Target a Specific Knowledge Base

To repair only a single knowledge base directory:

node knowledge-base/fix_markdown_links.js 14-surrealdb

---

3. How the Idempotent Repair Algorithm Works

The repair script reads markdown files line-by-line and applies an idempotent parsing pipeline:

1. Idempotent Bypass Check: Checks if the line is already valid (- [Title](../path/file.md) — Description or - [geometry (GeoJSON)](../path/file.md) — Description). If valid, the line is left completely untouched.
2. Double Bracket Cleaning: Removes any trailing duplicate closing brackets (e.g. [Label]]).
3. Targeted Extraction: Extracts relative paths (../level_XX/file.md), labels, and descriptions without corrupting titles that contain internal parentheses.

// 1. Check if line is ALREADY a valid Markdown link (idempotent bypass)
const validLinkRegex = /^(\s*-\s+)\[([^\]]+)\]\((?:\.\.\/|\.\/)[^\)]+\.md\)(\s*—\s*.*)$/;
if (validLinkRegex.test(line)) {
  return line; // ALREADY VALID! Do not modify!
}

---

4. Preventing Malformed Links in AI Generation Prompts

To prevent AI coding assistants from generating malformed links in future term documents, append the following explicit formatting rule to prompt guidelines:

---

5. Summary Checklist for Knowledge Base Audits

1. Run node knowledge-base/fix_markdown_links.js --all to clean existing term files.
2. Run node knowledge-base/check_links.js [kb_folder] to verify that all relative file targets physically exist on disk.
3. Commit and push the updated knowledge base files to Git.