fix(docs): preserve explicit search heading links

Author: waleedlatif1

apps/docs/AGENTS.md

@@ -14,6 +14,7 @@ Read [EDITORIAL_GUIDE.md](EDITORIAL_GUIDE.md) before editing documentation. It d
 - Edit generated API and CLI prose at its owner, then use the generation commands in the editorial guide. Do not hand-edit generated specifications, reference pages, or marked generated regions.
 - Preserve page URLs, operation IDs, method/path pairs, command options, authentication, and schema behavior. Validate copyable request bodies against the canonical input contracts.
 - Check inbound heading anchors from the entire docs site and application before renaming them. Use native explicit tab triggers for provider bookmarks, with `aria-controls` matching panel IDs; preserve the reciprocal `aria-labelledby` relationship and avoid duplicate element IDs.
+- Search citations must use the page's explicit heading IDs and omit the alias syntax from result titles.
 
 ## Layout and components
 

apps/docs/INTEGRATIONS_AUDIT.md

@@ -48,6 +48,8 @@ PR review checked the capability boundaries again against each operation. Correc
 
 ## Validation
 
+Search citation extraction now honors explicit heading IDs without including alias syntax in result titles. Retained parser regressions fail before the fix and when either ID preservation or label cleanup is removed; ordinary heading links remain unchanged.
+
 Completed local validation:
 
 - All three independent before/after reviews reached a qualified pass after their findings were corrected and reread.

apps/sim/lib/chunkers/docs-chunker.test.ts

@@ -6,7 +6,7 @@ import { describe, expect, it, vi } from 'vitest'
 
 vi.mock('@/lib/knowledge/embeddings', () => knowledgeEmbeddingsMock)
 
-import { mkdtemp, writeFile } from 'fs/promises'
+import { mkdtemp, rm, writeFile } from 'fs/promises'
 import { tmpdir } from 'os'
 import { join } from 'path'
 import { ChunkLimitExceededError } from '@/lib/chunkers/chunk-budget'
@@ -129,28 +129,6 @@ describe('DocsChunker output budget', () => {
  */
 describe('DocsChunker page title', () => {
   const NAV_LINK = '[Next](/docs/tables/workflow-columns)'
-  const PARAGRAPH =
-    'Tables store rows your workflows read and write. Columns are typed, and every write is validated against the schema before it lands, so a bad row never reaches a downstream block. '
-  const _BODY = `# Tables
-
-${PARAGRAPH.repeat(3)}
-
-## Querying rows
-
-Use the Table block to query, insert, or update rows from a workflow. ${PARAGRAPH.repeat(3)}
-
-## ${NAV_LINK}
-
-${NAV_LINK}
-`
-
-  async function _chunkPage(content: string) {
-    const dir = await mkdtemp(join(tmpdir(), 'docs-chunker-'))
-    const file = join(dir, 'tables.mdx')
-    await writeFile(file, content)
-    return new DocsChunker({ chunkSize: 100, chunkOverlap: 0 }).chunkMdxFile(file, dir)
-  }
-
   it('never resolves a link-only heading as the title', () => {
     expect(
       resolveDocumentTitle({}, [{ level: 2, text: NAV_LINK, anchor: 'next', position: 0 }])
@@ -163,3 +141,27 @@ ${NAV_LINK}
     ).toBe('Tables')
   })
 })
+
+describe('DocsChunker section links', () => {
+  it.each([
+    ['Use the block [#usage-instructions]', 'Use the block', 'usage-instructions'],
+    ['Renamed section [#Stable.ID-v2]', 'Renamed section', 'Stable.ID-v2'],
+    ['Ordinary heading', 'Ordinary heading', 'ordinary-heading'],
+  ])('links %s to its rendered section', async (heading, label, anchor) => {
+    const dir = await mkdtemp(join(tmpdir(), 'docs-section-links-'))
+    try {
+      const file = join(dir, 'guide.mdx')
+      await writeFile(
+        file,
+        `## ${heading}\n\nSearch results should take readers to the matching section of a page. Stable section identifiers preserve those links when headings change, and the result title should contain only the visible heading.`
+      )
+      const chunks = await new DocsChunker({ chunkOverlap: 0 }).chunkMdxFile(file, dir)
+
+      expect(chunks).toHaveLength(1)
+      expect(chunks[0]?.headerLink).toBe(`https://docs.sim.ai/guide#${anchor}`)
+      expect(chunks[0]?.headerText).toBe(label)
+    } finally {
+      await rm(dir, { recursive: true, force: true })
+    }
+  })
+})

apps/sim/lib/chunkers/docs-chunker.ts

@@ -218,10 +218,12 @@ export class DocsChunker {
 
     while ((match = headerRegex.exec(content)) !== null) {
       const level = match[1].length
-      const text = match[2].trim()
+      const rawText = match[2].trim()
+      const aliasMatch = /\s*\[#(.+?)]\s*$/.exec(rawText)
+      const text = aliasMatch ? rawText.slice(0, aliasMatch.index).trimEnd() : rawText
       // A heading that is only a link (`## [Next](…)`) is navigation, not a section.
       if (LINK_ONLY_LINE.test(text)) continue
-      const anchor = this.generateAnchor(text)
+      const anchor = aliasMatch?.[1] ?? this.generateAnchor(text)
 
       headers.push({
         text,