#!/bin/sh
# scripts/doxygen-md-filter.sh
#
# Doxygen FILTER for *.md files.  Rewrites repository-relative markdown links
# (e.g. `[label](doc/api/tests.md)` or `[label](architecture/foo.md)`) into
# basename-only form (`[label](tests.md)`, `[label](foo.md)`).
#
# Why: GitHub's markdown renderer needs the full relative path to resolve a
# link, but Doxygen indexes every .md file in INPUT by basename and treats
# any "/" in a link target as an unresolvable \ref.  Without this filter we
# get ~27 spurious warnings from README.md and CLAUDE.md.
#
# The filter is purely a Doxygen-side concern; the on-disk markdown is
# untouched, so GitHub rendering keeps working.
#
# Precondition: no two .md files in the project share a basename.  Verified
# at the time of writing by:
#   find . -name "*.md" -not -path "*/build*/*" -not -path "*/code/deps/*" \
#       -not -path "*/.git/*" | xargs -n1 basename | sort | uniq -c | awk '$1>1'
# (empty output ⇒ no collisions).
#
# Usage: configured via Doxyfile FILTER_PATTERNS = *.md=scripts/doxygen-md-filter.sh
set -eu
# Convert any markdown link target that points at a .md file into an HTML
# anchor.  Doxygen renders HTML verbatim and skips its (broken) \ref
# resolution; the rendered Doxygen HTML still hyperlinks to the source .md.
# Pattern: [label](path/to/file.md)  →  <a href="path/to/file.md">label</a>
sed -E 's#\[([^]]+)\]\(([a-zA-Z0-9_./-]+\.md)\)#<a href="\2">\1</a>#g' "$1"
