Fix LLM markdown output to preserve .md extensions for internal links and cross-links

[Copilot]

Fixes the LLM markdown renderer to preserve .md file extensions for internal markdown links and cross-links to markdown files while keeping external links and non-markdown cross-links as absolute URLs.

Problem

The LLM markdown output was converting all links to absolute URLs, including internal links to markdown pages and cross-links pointing to markdown files. This made the output less useful for LLM consumption where relative .md links are preferred for navigating between documentation pages.

For example, a link like [Getting Started](getting-started.md) would be rendered as [Getting Started](https://www.elastic.co/getting-started) in the LLM output, and a cross-link like [APM Guide](docs-content:/apm/guide.md) would become [APM Guide](https://docs.elastic.co/apm/guide).

Solution

Modified the LlmLinkInlineRenderer to intelligently detect different link types:

• Internal markdown links: Now preserve .md extensions (e.g., page.md)
• External links: Continue using absolute URLs (e.g., https://example.com)
• Cross-links to markdown files: Now preserve .md extensions as absolute URLs (e.g., https://docs.elastic.co/path/file.md)
• Cross-links to non-markdown: Continue using absolute URLs (e.g., https://docs.elastic.co/api)

The detection works by checking the Target{NavigationRoot} data that the diagnostic link parser sets on links pointing to markdown files, combined with the existing isCrossLink flag. For cross-links, the original URL is stored before resolution to determine if it pointed to a .md file.

Example

Given this markdown input:

This is a [link to another page](another-page.md).
This is an [external link](https://example.com).
This is a [cross-link to markdown](docs-content:/solutions/observability/apps/apm-server-binary.md).

The LLM output now correctly renders as:

This is a [link to another page](another-page.md).
This is an [external link](https://example.com).
This is a [cross-link to markdown](https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/solutions/observability/apps/apm-server-binary.md).

Testing

• Added comprehensive test coverage for all link types including cross-links
• All existing tests continue to pass (617 total, 0 failed)
• Verified functionality with actual docs-builder CLI output using --exporters llm

This change makes the LLM markdown output more useful for AI systems that need to understand the structure and relationships between documentation pages across different documentation sets.

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Feature Request]: Links in markdown output should also use .md link</issue_title>
<issue_description>### Prerequisites

• I have searched existing issues to ensure this feature hasn't already been requested
• I have tested using the latest version of docs-builder

What problem are you trying to solve?

The LLM markdown output produces internal and crosslinks and makes them absolute.

We should use the .md link also in the markdown content.

Proposed Solution

Change the LLM markdown link renderer to render markdown links if it's linking to a page.

Examples and Research

No response

Alternative Solutions

No response

Additional Context

No response

How important is this feature to you?

Nice to have</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes #1958

---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

[reakaleek]

@copilot

cross-links are absolute, but should also get a .md extension.

[Copilot]

Fixed in commit 8b0f20c. Cross-links to markdown files now preserve the .md extension and render as relative paths (e.g., solutions/observability/apps/apm-server-binary.md) instead of absolute URLs.

[reakaleek]

This doesn't look right. It still needs to become a full URL.

[reakaleek]

@copilot This doesn't look right. It still needs to become a full URL.

[Copilot]

Fixed in commit 75e3a94. Cross-links to markdown files now become full URLs with .md extensions (e.g., https://docs-v3-preview.elastic.dev/elastic/docs-content/tree/main/solutions/observability/apps/apm-server-binary.md) instead of relative paths.