feat: strip relative links to files outside the manifest

Relative links pointing to files not included in the manifest produce
broken links in the output. This change detects such links and strips
them — keeping only the label text and removing the URL — rather than
writing a broken relative path to the destination.

Two cases are covered:
- Relative link resolves in the source repo but the target file is not
  in the manifest (resolveDestinationNode returns nil)
- Relative link cannot be resolved in the source repo at all
  (ErrResourceNotFound from ResolveRelativeLink)

Absolute links that are not in the manifest continue to pass through
unchanged, preserving links to external documentation.

Author: VelmiraS

pkg/nodeplugins/markdown/document/document_worker.go

@@ -167,7 +167,11 @@ func (d *linkResolverTask) resolveLink(dest string, isEmbeddable bool) (string,
 			return dest, nil
 		}
 	}
-	return d.linkresolver.ResolveResourceLink(dest, d.node, d.source)
+	resolved, err := d.linkresolver.ResolveResourceLink(dest, d.node, d.source)
+	if err != nil {
+		return resolved, err
+	}
+	return resolved, nil
 }
 
 func (d *linkResolverTask) resolveEmbededLink(embeddedLink string, source string) (string, error) {

pkg/nodeplugins/markdown/document/markdown/link_modifier.go

@@ -7,12 +7,14 @@ package markdown
 import (
 	"bufio"
 	"bytes"
+	"errors"
 	"fmt"
 	"io"
 	"regexp"
 	"strings"
 	"sync"
 
+	"github.com/gardener/docforge/pkg/nodeplugins/markdown/linkresolver"
 	"github.com/yuin/goldmark/ast"
 	extast "github.com/yuin/goldmark/extension/ast"
 	"github.com/yuin/goldmark/renderer"
@@ -181,6 +183,7 @@ type Renderer struct {
 	markers      []int
 	emphasis     []byte
 	table        bool
+	linkStack    []int
 }
 
 // --------------------------- Node Renders
@@ -487,15 +490,27 @@ func (r *Renderer) renderEmphasis(node ast.Node, entering bool) (ast.WalkStatus,
 
 func (r *Renderer) renderLink(node ast.Node, entering bool) (ast.WalkStatus, error) {
 	if entering {
+		r.linkStack = append(r.linkStack, r.writer.Len())
 		_ = r.writer.WriteByte('[')
 	} else {
 		n := node.(*ast.Link)
-		_ = r.writer.WriteByte(']')
-		_ = r.writer.WriteByte('(')
 		dest, err := r.linkResolver(string(n.Destination), false)
+		var stripErr linkresolver.ErrStripLink
+		if errors.As(err, &stripErr) {
+			// strip link: remove the leading '[' and keep only the label text
+			labelStart := r.linkStack[len(r.linkStack)-1] + 1
+			r.linkStack = r.linkStack[:len(r.linkStack)-1]
+			label := bytes.Clone(r.writer.Bytes()[labelStart:])
+			r.writer.Truncate(labelStart - 1)
+			_, _ = r.writer.Write(label)
+			return ast.WalkContinue, nil
+		}
+		r.linkStack = r.linkStack[:len(r.linkStack)-1]
 		if err != nil {
 			return ast.WalkStop, err
 		}
+		_ = r.writer.WriteByte(']')
+		_ = r.writer.WriteByte('(')
 		wrap := wrapLinkDestination([]byte(dest))
 		if wrap {
 			_ = r.writer.WriteByte('<')

pkg/nodeplugins/markdown/document/markdown/link_modifier_test.go

@@ -9,6 +9,7 @@ import (
 	"errors"
 
 	"github.com/gardener/docforge/pkg/nodeplugins/markdown/document/markdown"
+	"github.com/gardener/docforge/pkg/nodeplugins/markdown/linkresolver"
 	. "github.com/onsi/ginkgo"
 	. "github.com/onsi/gomega"
 	"github.com/yuin/goldmark/ast"
@@ -139,6 +140,28 @@ var _ = Describe("Links modifier", func() {
 				Expect(err.Error()).To(ContainSubstring("fake-error"))
 			})
 		})
+		Context("strip link", func() {
+			BeforeEach(func() {
+				lr.strip = true
+				md = "text:\n[guide](../excluded/file.md) for details.\n"
+				exp = "text:\nguide for details.\n"
+			})
+			It("strips the link and keeps the label", func() {
+				Expect(err).NotTo(HaveOccurred())
+				Expect(buf.String()).To(Equal(exp))
+			})
+		})
+		Context("strip link with title", func() {
+			BeforeEach(func() {
+				lr.strip = true
+				md = "text:\n[guide](../excluded/file.md \"some title\") for details.\n"
+				exp = "text:\nguide for details.\n"
+			})
+			It("strips the link and title, keeps only label", func() {
+				Expect(err).NotTo(HaveOccurred())
+				Expect(buf.String()).To(Equal(exp))
+			})
+		})
 	})
 	When("Render markdown with images", func() {
 		BeforeEach(func() {
@@ -233,11 +256,15 @@ var _ = Describe("Links modifier", func() {
 })
 
 type linkResolver struct {
-	dst string
-	err error
+	dst  string
+	err  error
+	strip bool
 }
 
 // implements markdown.ResolveLink and fakes the result
-func (lr *linkResolver) fakeLink(_ string, _ bool) (string, error) {
+func (lr *linkResolver) fakeLink(dest string, _ bool) (string, error) {
+	if lr.strip {
+		return "", linkresolver.ErrStripLink{Destination: dest}
+	}
 	return lr.dst, lr.err
 }

pkg/nodeplugins/markdown/linkresolver/link_resolving.go

@@ -21,6 +21,16 @@ import (
 
 //go:generate go run github.com/maxbrunsfeld/counterfeiter/v6 -generate -header ../../../../license_prefix.txt
 
+// ErrStripLink is returned by ResolveResourceLink when a relative link points to a file
+// not included in the manifest. The renderer should strip the link and keep only the label text.
+type ErrStripLink struct {
+	Destination string
+}
+
+func (e ErrStripLink) Error() string {
+	return "link destination not in manifest: " + e.Destination
+}
+
 // Interface resolves links URLs
 //
 //counterfeiter:generate . Interface
@@ -62,8 +72,9 @@ func (l *LinkResolver) ResolveResourceLink(resourceLink string, node *manifest.N
 	if strings.HasPrefix(resourceLink, "#") {
 		return resourceLink, nil
 	}
+	wasRelative := repositoryhost.IsRelative(resourceLink)
 	// handle relative links to resources
-	if repositoryhost.IsRelative(resourceLink) {
+	if wasRelative {
 		var err error
 		if srcURL, e := l.Repositoryhosts.ResourceURL(source); e == nil {
 			resourceLink = ReAnchorRootAbsolute(resourceLink, srcURL.GetResourcePath(), l.Hugo.HugoStructuralDirs)
@@ -72,9 +83,8 @@ func (l *LinkResolver) ResolveResourceLink(resourceLink string, node *manifest.N
 		resourceLink, err = l.Repositoryhosts.ResolveRelativeLink(source, resourceLink)
 		if err != nil {
 			if _, ok := err.(repositoryhost.ErrResourceNotFound); ok {
-				klog.Warningf("failed to validate absolute link for %s from source %s: %v\n", resourceLink, source, err)
-				// don't process broken link and don't return error
-				return resourceLink, nil
+				klog.V(6).Infof("stripping relative link %s from source %s — target not found in repository", resourceLink, source)
+				return "", ErrStripLink{Destination: resourceLink}
 			}
 			return resourceLink, err
 		}
@@ -86,7 +96,15 @@ func (l *LinkResolver) ResolveResourceLink(resourceLink string, node *manifest.N
 	destinationResourceURL := destinationResource.ResourceURL()
 	destinationNode, err := l.resolveDestinationNode(destinationResourceURL, node)
 	if destinationNode == nil {
-		return resourceLink, err
+		if err != nil {
+			return resourceLink, err
+		}
+		if wasRelative {
+			klog.V(6).Infof("stripping relative link %s (resolved to %s) — not found in manifest", resourceLink, destinationResourceURL)
+			return "", ErrStripLink{Destination: resourceLink}
+		}
+		klog.V(6).Infof("passing through absolute link %s — not found in manifest", destinationResourceURL)
+		return resourceLink, nil
 	}
 
 	// construct destination from node path

pkg/nodeplugins/markdown/linkresolver/link_resolving_test.go

@@ -6,6 +6,7 @@ package linkresolver_test
 
 import (
 	"embed"
+	"errors"
 	"testing"
 
 	_ "embed"
@@ -59,10 +60,11 @@ var _ = Describe("Document link resolving", func() {
 			node = linkResolver.SourceToNode[source][0]
 		})
 
-		It("Broken links should not return error", func() {
+		It("Relative links to files not in repository are stripped", func() {
 			newLink, err := linkResolver.ResolveResourceLink("invalidfoo/bar.md", node, source)
-			Expect(err).To(Not(HaveOccurred()))
-			Expect(newLink).To(Equal("https://github.com/gardener/docforge/blob/master/invalidfoo/bar.md"))
+			var stripErr linkresolver.ErrStripLink
+			Expect(errors.As(err, &stripErr)).To(BeTrue())
+			Expect(newLink).To(Equal(""))
 		})
 
 		It("Resolves linking closest source correctly", func() {
@@ -91,8 +93,9 @@ var _ = Describe("Document link resolving", func() {
 
 		It("Resolves non-page resource links correctly", func() {
 			newLink, err := linkResolver.ResolveResourceLink("./non-page.md", node, source)
-			Expect(err).ToNot(HaveOccurred())
-			Expect(newLink).To(Equal("https://github.com/gardener/docforge/blob/master/non-page.md"))
+			var stripErr linkresolver.ErrStripLink
+			Expect(errors.As(err, &stripErr)).To(BeTrue())
+			Expect(newLink).To(Equal(""))
 		})
 
 		It("Resolving url with no suitable repository host", func() {