[EUI+] Investigate Markdown link replacement

[weronikaolejniczak]

Warning

We should investigate this just before releasing M1. We can potentially move it to M2 if it turns out to be a big task.

The purpose of this spike is to investigate Markdown link replacement by Docusaurus and come up with possible solutions.

---

Currently, we use both URL and file paths in Markdown links. The Markdown loader will convert the file path to the target file's URL path. If the path cannot be resolved, it triggers a warning (as defined in docusaurus.config.ts). The link gets replaced with an anchor tag. Other Markdown links get wrapped with a swizzled MDXContent.A component (which in our case is an EuiLink component). Both types of links have different styles.

We have decided to use relative file paths to reap the benefits:

• Links will keep working on the GitHub interface and many Markdown editors
• You can customize the files' slugs without having to update all the links
• Moving files around the folders can be tracked by your editor, and some editors may automatically update file links
• A versioned doc will link to another doc of the exact same version
• Relative URL links are very likely to break if you update the trailingSlash config

Source: Markdown links | Docusaurus

After #8158 has been concluded the majority of links will use relative file paths except for external links which should use Link component directly (it adds target="_blank" rel="noopener noreferrer" automatically). None of the links will use our EuiLink.

---

Additionally, all links in the Homepage are not reported broken. We should either make them use Docusaurus Link component or useBrokenLinks hook.

Sometimes, we bold Eui* links (comment), most of the time we don't. We need to decide on a consistent way and if possible apply it globally, without the need for local ** syntax each time we deal with EUI components.