feat(gatsby): Add support for relative links

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:

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, and instead follow [the behavior of @reach/router](https://reach.tech/router/nesting). This avoids 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.

e2e-tests/development-runtime/cypress/integration/navigation/linking.js

@@ -33,6 +33,42 @@ describe(`navigation`, () => {
     cy.location(`pathname`).should(`equal`, `/`)
   })
 
+  describe(`relative links`, () => {
+    it(`can navigate to a subdirectory`, () => {
+      cy.getTestElement(`subdir-link`)
+        .click()
+        .location(`pathname`)
+        .should(`eq`, `/subdirectory/page-1`)
+    })
+
+    it(`can navigate to a sibling page`, () => {
+      cy.visit(`/subdirectory/page-1`)
+        .waitForRouteChange()
+        .getTestElement(`page-2-link`)
+        .click()
+        .location(`pathname`)
+        .should(`eq`, `/subdirectory/page-2`)
+    })
+
+    it(`can navigate to a parent page`, () => {
+      cy.visit(`/subdirectory/page-1`)
+        .waitForRouteChange()
+        .getTestElement(`page-parent-link`)
+        .click()
+        .location(`pathname`)
+        .should(`eq`, `/subdirectory`)
+    })
+
+    it(`can navigate to a sibling page programatically`, () => {
+      cy.visit(`/subdirectory/page-1`)
+        .waitForRouteChange()
+        .getTestElement(`page-2-button-link`)
+        .click()
+        .location(`pathname`)
+        .should(`eq`, `/subdirectory/page-2`)
+    })
+  })
+
   describe(`non-existent route`, () => {
     beforeEach(() => {
       cy.getTestElement(`broken-link`).click().waitForRouteChange()

e2e-tests/development-runtime/src/pages/index.js

@@ -26,6 +26,9 @@ const IndexPage = ({ data }) => (
     <Link to="/__non_existent_page__/" data-testid="broken-link">
       Go to a broken link
     </Link>
+    <Link to="subdirectory/page-1" data-testid="subdir-link">
+      Go to subdirectory
+    </Link>
     <h2>Blog posts</h2>
     <ul>
       {data.posts.edges.map(({ node }) => (

e2e-tests/development-runtime/src/pages/subdirectory/index.js

@@ -0,0 +1,23 @@
+import * as React from "react"
+import { Link, navigate } from "gatsby"
+
+import Layout from "../../components/layout"
+
+const IndexPage = () => (
+  <Layout>
+    <h1>Hi people</h1>
+    <p>Welcome to your new Gatsby site.</p>
+    <p>Now go build something great.</p>
+    <Link data-testid="page-2-link" to="./page-2/">
+      Go to page 2
+    </Link>
+    <button
+      data-testid="page-2-button-link"
+      onClick={() => navigate(`./page-2/`)}
+    >
+      Go to page 2 with navigate()
+    </button>
+  </Layout>
+)
+
+export default IndexPage

e2e-tests/development-runtime/src/pages/subdirectory/page-1.js

@@ -0,0 +1,26 @@
+import * as React from "react"
+import { Link, navigate } from "gatsby"
+
+import Layout from "../../components/layout"
+
+const IndexPage = () => (
+  <Layout>
+    <h1>Hi people</h1>
+    <p>Welcome to your new Gatsby site.</p>
+    <p>Now go build something great.</p>
+    <Link data-testid="page-2-link" to="../page-2/">
+      Go to page 2
+    </Link>
+    <Link data-testid="page-parent-link" to="..">
+      Go up
+    </Link>
+    <button
+      data-testid="page-2-button-link"
+      onClick={() => navigate(`../page-2/`)}
+    >
+      Go to page 2 with navigate()
+    </button>
+  </Layout>
+)
+
+export default IndexPage

e2e-tests/development-runtime/src/pages/subdirectory/page-2.js

@@ -0,0 +1,16 @@
+import * as React from "react"
+import { Link } from "gatsby"
+
+import Layout from "../../components/layout"
+
+const SecondPage = () => (
+  <Layout>
+    <h1>Hi from the second page</h1>
+    <p>Welcome to page 2</p>
+    <Link data-testid="index-link" to="../page-1">
+      Go back to page 1
+    </Link>
+  </Layout>
+)
+
+export default SecondPage

e2e-tests/path-prefix/cypress/integration/navigate.js

@@ -24,6 +24,42 @@ describe(`navigate`, () => {
       .should(`eq`, withTrailingSlash(pathPrefix))
   })
 
+  describe(`relative links`, () => {
+    it(`can navigate to a subdirectory`, () => {
+      cy.getTestElement(`subdir-link`)
+        .click()
+        .location(`pathname`)
+        .should(`eq`, `${pathPrefix}/subdirectory/page-1`)
+    })
+
+    it(`can navigate to a sibling page`, () => {
+      cy.visit(`/subdirectory/page-1`)
+        .waitForRouteChange()
+        .getTestElement(`page-2-link`)
+        .click()
+        .location(`pathname`)
+        .should(`eq`, `${pathPrefix}/subdirectory/page-2`)
+    })
+
+    it(`can navigate to a parent page`, () => {
+      cy.visit(`/subdirectory/page-1`)
+        .waitForRouteChange()
+        .getTestElement(`page-parent-link`)
+        .click()
+        .location(`pathname`)
+        .should(`eq`, `${pathPrefix}/subdirectory`)
+    })
+
+    it(`can navigate to a sibling page programatically`, () => {
+      cy.visit(`/subdirectory/page-1`)
+        .waitForRouteChange()
+        .getTestElement(`page-2-button-link`)
+        .click()
+        .location(`pathname`)
+        .should(`eq`, `${pathPrefix}/subdirectory/page-2`)
+    })
+  })
+
   it(`can navigate to 404`, () => {
     cy.getTestElement(`404-link`).click().waitForRouteChange()
 

e2e-tests/path-prefix/src/pages/index.js

@@ -23,6 +23,9 @@ const IndexPage = () => (
     <Link data-testid="404-link" to="/not-existing-page">
       Go to not existing page
     </Link>
+    <Link data-testid="subdir-link" to="subdirectory/page-1">
+      Go to subdirectory
+    </Link>
   </Layout>
 )
 

e2e-tests/path-prefix/src/pages/subdirectory/index.js

@@ -0,0 +1,23 @@
+import * as React from "react"
+import { Link, navigate } from "gatsby"
+
+import Layout from "../../components/layout"
+
+const IndexPage = () => (
+  <Layout>
+    <h1>Hi people</h1>
+    <p>Welcome to your new Gatsby site.</p>
+    <p>Now go build something great.</p>
+    <Link data-testid="page-2-link" to="./page-2/">
+      Go to page 2
+    </Link>
+    <button
+      data-testid="page-2-button-link"
+      onClick={() => navigate(`./page-2/`)}
+    >
+      Go to page 2 with navigate()
+    </button>
+  </Layout>
+)
+
+export default IndexPage

e2e-tests/path-prefix/src/pages/subdirectory/page-1.js

@@ -0,0 +1,26 @@
+import * as React from "react"
+import { Link, navigate } from "gatsby"
+
+import Layout from "../../components/layout"
+
+const IndexPage = () => (
+  <Layout>
+    <h1>Hi people</h1>
+    <p>Welcome to your new Gatsby site.</p>
+    <p>Now go build something great.</p>
+    <Link data-testid="page-2-link" to="../page-2/">
+      Go to page 2
+    </Link>
+    <Link data-testid="page-parent-link" to="..">
+      Go up
+    </Link>
+    <button
+      data-testid="page-2-button-link"
+      onClick={() => navigate(`../page-2/`)}
+    >
+      Go to page 2 with navigate()
+    </button>
+  </Layout>
+)
+
+export default IndexPage

e2e-tests/path-prefix/src/pages/subdirectory/page-2.js

@@ -0,0 +1,16 @@
+import * as React from "react"
+import { Link } from "gatsby"
+
+import Layout from "../../components/layout"
+
+const SecondPage = () => (
+  <Layout>
+    <h1>Hi from the second page</h1>
+    <p>Welcome to page 2</p>
+    <Link data-testid="index-link" to="../page-1">
+      Go back to page 1
+    </Link>
+  </Layout>
+)
+
+export default SecondPage

e2e-tests/production-runtime/cypress/integration/1-production.js

@@ -43,6 +43,44 @@ describe(`Production build tests`, () => {
       .should(`equal`, `/page-2/`)
   })
 
+  describe(`relative links`, () => {
+    it(`should navigate to a subdirectory`, () => {
+      cy.visit(`/`)
+        .waitForRouteChange()
+        .getTestElement(`subdir-link`)
+        .click()
+        .location(`pathname`)
+        .should(`eq`, `/subdirectory/page-1`)
+    })
+
+    it(`can navigate to a sibling page`, () => {
+      cy.visit(`/subdirectory/page-1`)
+        .waitForRouteChange()
+        .getTestElement(`page-2-link`)
+        .click()
+        .location(`pathname`)
+        .should(`eq`, `/subdirectory/page-2`)
+    })
+
+    it(`can navigate to a parent page`, () => {
+      cy.visit(`/subdirectory/page-1`)
+        .waitForRouteChange()
+        .getTestElement(`page-parent-link`)
+        .click()
+        .location(`pathname`)
+        .should(`eq`, `/subdirectory`)
+    })
+
+    it(`can navigate to a sibling page programatically`, () => {
+      cy.visit(`/subdirectory/page-1`)
+        .waitForRouteChange()
+        .getTestElement(`page-2-button-link`)
+        .click()
+        .location(`pathname`)
+        .should(`eq`, `/subdirectory/page-2`)
+    })
+  })
+
   it(`should show 404 page when clicking a link to a non-existent page route`, () => {
     cy.visit(`/`).waitForRouteChange()
 

e2e-tests/production-runtime/src/pages/index.js

@@ -61,6 +61,11 @@ const IndexPage = ({ pageContext }) => (
           Go to page with unicode path
         </Link>
       </li>
+      <li>
+        <Link to="subdirectory/page-1" data-testid="subdir-link">
+          Go to subdirectory
+        </Link>
+      </li>
     </ul>
   </Layout>
 )

e2e-tests/production-runtime/src/pages/subdirectory/index.js

@@ -0,0 +1,23 @@
+import * as React from "react"
+import { Link, navigate } from "gatsby"
+
+import Layout from "../../components/layout"
+
+const IndexPage = () => (
+  <Layout>
+    <h1>Hi people</h1>
+    <p>Welcome to your new Gatsby site.</p>
+    <p>Now go build something great.</p>
+    <Link data-testid="page-2-link" to="./page-2/">
+      Go to page 2
+    </Link>
+    <button
+      data-testid="page-2-button-link"
+      onClick={() => navigate(`./page-2/`)}
+    >
+      Go to page 2 with navigate()
+    </button>
+  </Layout>
+)
+
+export default IndexPage

e2e-tests/production-runtime/src/pages/subdirectory/page-1.js

@@ -0,0 +1,26 @@
+import * as React from "react"
+import { Link, navigate } from "gatsby"
+
+import Layout from "../../components/layout"
+
+const IndexPage = () => (
+  <Layout>
+    <h1>Hi people</h1>
+    <p>Welcome to your new Gatsby site.</p>
+    <p>Now go build something great.</p>
+    <Link data-testid="page-2-link" to="../page-2/">
+      Go to page 2
+    </Link>
+    <Link data-testid="page-parent-link" to="..">
+      Go up
+    </Link>
+    <button
+      data-testid="page-2-button-link"
+      onClick={() => navigate(`../page-2/`)}
+    >
+      Go to page 2 with navigate()
+    </button>
+  </Layout>
+)
+
+export default IndexPage

e2e-tests/production-runtime/src/pages/subdirectory/page-2.js

@@ -0,0 +1,16 @@
+import * as React from "react"
+import { Link } from "gatsby"
+
+import Layout from "../../components/layout"
+
+const SecondPage = () => (
+  <Layout>
+    <h1>Hi from the second page</h1>
+    <p>Welcome to page 2</p>
+    <Link data-testid="index-link" to="../page-1">
+      Go back to page 1
+    </Link>
+  </Layout>
+)
+
+export default SecondPage