Internal links: Absolute/Custom vs Relative

[pedro-psb]

Question:

Should we always use relative paths for internal links or use some custom solution for using absolute links?

This sample illustrates the difference in the usage of those options:

## Given a file structure:
guides/
    overview.md
    rpm/
        guide-1.md
getting-started/
    overview.md

# editing "guides/rpm/guide-1.md"
[link](../../getting-started/overview.md) # relative

# editing "guides/overview.md"
[link](../getting-started/overview.md) # relative (changed relative path)

# regardless of file being edited
[link](getting-started/overview.md) # absolute
[link](site:getting-started/overview.md) # custom (mkdocs-site-urls)
[link]({{base_url}}/getting-started/overview.md) # custom (mkdocs-macros-plugin)

Tradeoffs of using absolute

Cons

When using internal links, mkdocs recommends only using relative paths because absolute links (e.g. [link](/foo.md)) have some issues:

• Less portability: different markdown parsers may interpret this differently. E.g: may work in localserver but not in Github navigation pages
• Localserver vs Hosting Domain: if the hosting domain uses some prefix (https://mysite.org/prefix/), absolute link will refer to that and won't work.

Pros

• Easier to create: From the perspective of the contributor, he'll always need to "calculate" the relative path depending of the file the link is contained. If using the absolute path, we would use a more predictable link regardless of the page we're editing.
• Custom anyway: Because we're aggregating different repos into one, they would be broken even if using the more global relative-link approach, so adding another custom way of adding links would't hurt the portability too much.

References

https://www.mkdocs.org/user-guide/writing-your-docs/#linking-to-pages https://github.com/mkdocs/mkdocs/issues/192 https://github.com/mkdocs/mkdocs/issues/1592

[pedro-psb]

After discussing with the workgroup, we've decided to use absolute links because it is easier for contributors.