-
Notifications
You must be signed in to change notification settings - Fork 25.1k
Description
From #35974 (comment) and looking at the file ...
- Use relative links (for example,
../folder/file.mdor./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 ...
- 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.