Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

fix(markdown): match GitHub anchor slugs for headings with punctuation (#3673)

bianbiandashen7b8b33e8f8db
diff --git a/openviking/parse/parsers/markdown.py b/openviking/parse/parsers/markdown.py
index 3a10c9111..b3615b50b 100644
--- a/openviking/parse/parsers/markdown.py
+++ b/openviking/parse/parsers/markdown.py
@@ -97,7 +97,12 @@ def _gh_slug(text: str) -> str:
"""GitHub-style heading slug: lowercase, strip punctuation, spaces→'-', keep CJK."""
s = text.strip().lower()
s = re.sub(r"[^\w\s-]", "", s)
- s = re.sub(r"\s+", "-", s)
+ # Map each whitespace character to its own hyphen (do NOT collapse runs).
+ # GitHub's reference slugger does `.replace(/ /g, '-')` — one hyphen per
+ # space, no collapsing. Removing punctuation can leave adjacent spaces
+ # (e.g. "Foo & Bar" → "foo bar"); collapsing them produces "foo-bar"
+ # while GitHub generates "foo--bar", breaking intra-doc anchor links.
+ s = re.sub(r"\s", "-", s)
return s
diff --git a/tests/parse/test_gh_slug.py b/tests/parse/test_gh_slug.py
new file mode 100644
index 000000000..9c724586e
--- /dev/null
+++ b/tests/parse/test_gh_slug.py
@@ -0,0 +1,26 @@
+"""Regression test: _gh_slug must match GitHub's heading-anchor algorithm.
+
+GitHub's reference slugger (github-slugger) lowercases, strips a set of
+punctuation, then maps *each* space to a hyphen individually
+(``.replace(/ /g, '-')``) — it does not collapse consecutive whitespace.
+
+Because punctuation is removed *before* spaces are converted, a heading like
+"Foo & Bar" leaves two adjacent spaces where "&" was, which GitHub renders as
+a double hyphen ("foo--bar"). The intra-document link rewriter compares
+_gh_slug(heading) against the link fragment, so collapsing whitespace made
+links such as `guide.md#foo--bar` fail to resolve.
+"""
+
+from openviking.parse.parsers.markdown import _gh_slug
+
+
+def test_gh_slug_matches_github_for_removed_punctuation():
+ # "&" removed -> "foo bar" (two spaces) -> "foo--bar" on GitHub.
+ assert _gh_slug("Foo & Bar") == "foo--bar"
+ assert _gh_slug("Terms & Conditions") == "terms--conditions"
+
+
+def test_gh_slug_simple_headings_unchanged():
+ assert _gh_slug("Hello World") == "hello-world"
+ assert _gh_slug("Section 1") == "section-1"
+ assert _gh_slug("C++ Guide") == "c-guide"