fix(cli): resolve Markdown snippet references in link targets for broken link checking (#12488)

* fix(cli): resolve Markdown snippet references in link targets for broken link checking

Co-Authored-By: ryanstep@buildwithfern.com <ryanstep@umich.edu>

* refactor: use existing replaceReferencedMarkdown instead of custom snippet resolution

Co-Authored-By: ryanstep@buildwithfern.com <ryanstep@umich.edu>

* feat: surface snippet resolution warnings as rule violations

Co-Authored-By: ryanstep@buildwithfern.com <ryanstep@umich.edu>

* revert: remove snippet warning logging, use NOOP_CONTEXT for snippet resolution

Co-Authored-By: ryanstep@buildwithfern.com <ryanstep@umich.edu>

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

Author: Ryan-Amirthan

packages/cli/cli/versions.yml

@@ -1,4 +1,12 @@
 # yaml-language-server: $schema=../../../fern-versions-yml.schema.json
+- version: 3.79.2
+  changelogEntry:
+    - summary: |
+        Fix `fern check --strict-broken-links` to resolve `<Markdown src="..." />` snippets used
+        inside link targets.
+      type: fix
+  createdAt: "2026-02-17"
+  irVersion: 65
 - version: 3.79.1
   changelogEntry:
     - summary: |

packages/cli/ete-tests/src/tests/broken-links/broken-links.test.ts

@@ -41,6 +41,14 @@ describe("fern docs broken-links", () => {
         expect(stripAnsi(stdout)).toContain("All checks passed");
     }, 20_000);
 
+    it("links with Markdown snippet references should be resolved", async () => {
+        const { stdout } = await runFernCli(["docs", "broken-links"], {
+            cwd: join(fixturesDir, RelativeFilePath.of("snippet-link")),
+            reject: false
+        });
+        expect(stripAnsi(stdout)).toContain("All checks passed");
+    }, 20_000);
+
     it("broken links in sections with path property should be detected", async () => {
         const { stdout } = await runFernCli(["docs", "broken-links"], {
             cwd: join(fixturesDir, RelativeFilePath.of("section-with-path")),

packages/cli/ete-tests/src/tests/broken-links/fixtures/snippet-link/fern/docs.yml

@@ -0,0 +1,8 @@
+instances:
+  - url: docs.example.com
+
+navigation:
+  - page: Test
+    path: test.mdx
+  - page: Getting Started
+    path: getting-started.mdx

packages/cli/ete-tests/src/tests/broken-links/fixtures/snippet-link/fern/fern.config.json

@@ -0,0 +1,4 @@
+{
+  "organization": "test-org",
+  "version": "0.0.0"
+}

packages/cli/ete-tests/src/tests/broken-links/fixtures/snippet-link/fern/getting-started.mdx

@@ -0,0 +1,3 @@
+# Getting Started
+
+Welcome to the getting started guide.

packages/cli/ete-tests/src/tests/broken-links/fixtures/snippet-link/fern/snippets/valid-link.mdx

@@ -0,0 +1 @@
+/getting-started

packages/cli/ete-tests/src/tests/broken-links/fixtures/snippet-link/fern/test.mdx

@@ -0,0 +1,5 @@
+# Test Snippet Links
+
+This page tests that links with Markdown snippet references are resolved correctly.
+
+[Getting Started](<Markdown src="./snippets/valid-link.mdx" />)

packages/cli/yaml/docs-validator/src/rules/valid-markdown-link/valid-markdown-link.ts

@@ -1,5 +1,6 @@
 import { SourceResolverImpl } from "@fern-api/cli-source-resolver";
 import { noop } from "@fern-api/core-utils";
+import { replaceReferencedMarkdown } from "@fern-api/docs-markdown-utils";
 import { convertIrToApiDefinition, DocsDefinitionResolver } from "@fern-api/docs-resolver";
 import { APIV1Read, ApiDefinition, FernNavigation } from "@fern-api/fdr-sdk";
 import { AbsoluteFilePath, join, RelativeFilePath, relative } from "@fern-api/fs-utils";
@@ -94,8 +95,15 @@ export const ValidMarkdownLinks: Rule = {
                     return [];
                 }
 
+                const { markdown: resolvedContent } = await replaceReferencedMarkdown({
+                    markdown: content,
+                    absolutePathToFernFolder: workspace.absoluteFilePath,
+                    absolutePathToMarkdownFile: absoluteFilepath,
+                    context: NOOP_CONTEXT
+                });
+
                 // Find all matches in the Markdown text
-                const { pathnamesToCheck, violations } = collectPathnamesToCheck(content, {
+                const { pathnamesToCheck, violations } = collectPathnamesToCheck(resolvedContent, {
                     absoluteFilepath,
                     instanceUrls
                 });