You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
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:
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:https://mysite.org/prefix/
), absolute link will refer to that and won't work.Pros
References
https://www.mkdocs.org/user-guide/writing-your-docs/#linking-to-pages
mkdocs/mkdocs#192
mkdocs/mkdocs#1592
The text was updated successfully, but these errors were encountered: