Skip to content

Copilot guidance updates for linksΒ #35975

@guardrex

Description

@guardrex

From #35974 (comment) and looking at the file ...

  • Use relative links (for example, ../folder/file.md or ./file.md) when referencing files within this repository. Do not use absolute URLs or GitHub web links for internal content.

It needs a bit more guidance there. For one thing, it should be told to use XREF article cross-links for markdown files, not .md physical locations. Perhaps, use something that we wouldn't use with triple-colon link notation, like a PowerShell script that we intend to cross-link (not show in the article). Second, it seems confused about external links beyond this. It probably should be told that for external links to non-Learn sites that it's OK to use absolute URLs.

For this bit ...

  • Example (Microsoft Learn):
  • Original: https://learn.microsoft.com/en-us/aspnet/core/blazor/
  • Correct: https://learn.microsoft.com/aspnet/core/blazor/

I think that should be replaced entirely with an external (non-Learn site) link example. It's showing Copilot a bad "correct" link. We'd use the XREF to the index page of the Blazor node (xref:blazor/index).

Perhaps, use an MDN example ...

The last one isn't good for the aforementioned reason ...

  • For Microsoft Learn links, also strip the base domain (https://learn.microsoft.com/en-us) so only the path remains.
  • Example:
    • Original: https://learn.microsoft.com/en-us/aspnet/core/blazor/
    • Correct: /aspnet/core/blazor/

That would be an XREF here. Recommend using one of the .NET docs articles.


Associated WorkItem - 482776

Metadata

Metadata

Assignees

Labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions