Add docs for relative links

gatsbyjs · May 20, 2020 · 5bedec1 · 5bedec1
1 parent 545ff9d
commit 5bedec1
Show file tree

Hide file tree

Showing 2 changed files with 8 additions and 0 deletions.
diff --git a/docs/docs/gatsby-link.md b/docs/docs/gatsby-link.md
@@ -348,6 +348,10 @@ const Link = ({ children, to, activeClassName, partiallyActive, ...other }) => {
 export default Link
 ```
 
+### Relative links
+
+The `<Link />` component follows [the behavior of @reach/router](https://reach.tech/router/nesting) by ignoring trailing slashes and treating each page as if it were a directory when resolving relative links. For example if you are on either `/blog/my-great-page` or `/blog/my-great-page/` (note the trailing slash), a link to `../second-page` will take you to `/blog/second-page`.
+
 ### File Downloads
 
 You can similarly check for file downloads:

diff --git a/docs/docs/linking-between-pages.md b/docs/docs/linking-between-pages.md
@@ -31,6 +31,10 @@ The above code will add a link to the contact page, automatically rendered in HT
 
 > **Note:** the value `"/"` for the `to` property will take users to the home page.
 
+## Using relative links in the `<Link />` component
+
+Relative links are ones where the `to` property doesn't start with a `/`. These behave slightly different from regular browser links. They follow [the behavior of @reach/router](https://reach.tech/router/nesting). This avoid confusion with trailing slashes by ignoring them entirely and treating every page as if it were a directory. For example, if you are on either `/blog/my-great-page` or `/blog/my-great-page/` (note the trailing slash), a link to `../second-page` will take you to `/blog/second-page`. Similarly, if you are on `/blog` or `/blog/` a link to `hello-world` will take you to `/blog/hello-world`.
+
 ## Using `<a>` for external links
 
 If you are linking to pages not handled by your Gatsby site (such as on a different domain), you should use the native HTML `<a>` tag instead of Gatsby Link.