fix: wiki links now display clean page title instead of raw path

[[docs/contributing/index]] → displays as 'Contributing' (not 'docs/contributing/index')
[[docs/strategies/collective-awakening]] → displays as 'Collective Awakening'
Pipe syntax still overrides: [[page|custom text]] uses the custom text.
Images keep raw filename as alt text.

_extensions/wikilinks.py

@@ -93,6 +93,37 @@ def _url_from_link(link: str) -> str:
     return "/" + "/".join(parts) + "/"
 
 
+def _display_name(link: str) -> str:
+    """Derive a human-readable title from a wiki link path.
+
+    ``[[docs/contributing/index]]`` → ``Contributing``
+    ``[[docs/strategies/collective-awakening]]`` → ``Collective Awakening``
+    ``[[Contributing]]`` → ``Contributing``
+    """
+    raw = link.strip()
+
+    # Strip .md extension
+    raw = re.sub(r"\.md$", "", raw, flags=re.IGNORECASE)
+
+    # Strip docs/ prefix
+    if raw.lower().startswith(_DOCS_PREFIX):
+        raw = raw[len(_DOCS_PREFIX) :]
+
+    parts = [p for p in raw.split("/") if p]
+    if not parts:
+        return link
+
+    # If the last component is "index", use the parent directory name
+    if parts[-1].lower() == "index":
+        name = parts[-2] if len(parts) >= 2 else parts[-1]
+    else:
+        name = parts[-1]
+
+    # Replace hyphens/underscores with spaces, title-case
+    name = name.replace("-", " ").replace("_", " ")
+    return name.title()
+
+
 class WikilinksPreprocessor(Preprocessor):
     """Preprocessor that converts [[wikilinks]] to root-relative [text](/url/)."""
 
@@ -121,7 +152,7 @@ class WikilinksPreprocessor(Preprocessor):
         is_image = groups.get("image") or ""
         link = groups.get("link") or ""
         anchor = groups.get("anchor") or ""
-        text = groups.get("text") or link or anchor
+        text = groups.get("text") or (link if is_image else _display_name(link)) or anchor
 
         if not (link or text or anchor):
             return match.group(0)