[docs][recipes] Update to Linking Between Recipe with example + tests (…

…#21854)

* update create page recipe example

* updates to Linking Between Pages recipe

* add Linking Between Pages recipe example

* update port to one specific to cypress tests

Co-authored-by: gatsbybot <mathews.kyle+gatsbybot@gmail.com>

docs/docs/recipes/pages-layouts.md

@@ -74,33 +74,39 @@ export default AboutPage
 
 ## Linking between pages
 
-Routing in Gatsby relies on the `<Link />` component.
+Routing for links internal to your Gatsby site relies on the `<Link />` component.
 
 ### Prerequisites
 
 - A Gatsby site with two page components: `index.js` and `contact.js`
-- The Gatsby `<Link />` component
 - The [Gatsby CLI](/docs/gatsby-cli/) to run `gatsby develop`
 
 ### Directions
 
-1. Open the index page component (`src/pages/index.js`), import the `<Link />` component from Gatsby, add a `<Link />` component above the header, and give it a `to` property with the value of `"/contact/"` for the pathname:
+1. Open the index page component (`src/pages/index.js`) and import the `<Link />` component from Gatsby. Add a `<Link />` component to the JSX code and give it a `to` property with the pathname value of `"/contact/"` to output an HTML link with Gatsby powers:
 
 ```jsx:title=src/pages/index.js
 import React from "react"
-import { Link } from "gatsby"
+import { Link } from "gatsby" // highlight-line
 
 export default () => (
-  <div style={{ color: `purple` }}>
-    <Link to="/contact/">Contact</Link>
-    <p>What a world.</p>
-  </div>
+  <main>
+    <h1>What a world.</h1>
+    <p>
+      <Link to="/contact/">Contact</Link> // highlight-line
+    </p>
+  </main>
 )
 ```
 
 2. Run `gatsby develop` and navigate to the index page. You should have a link that takes you to the contact page when clicked!
 
-> **Note**: Gatsby's `<Link />` component is a wrapper around [`@reach/router`'s Link component](https://reach.tech/router/api/Link). For more information about Gatsby's `<Link />` component, consult the [API reference for `<Link />`](/docs/gatsby-link/).
+> **Note**: Gatsby's `<Link />` component is a wrapper around [`@reach/router`'s Link component](https://reach.tech/router/api/Link). It outputs an HTML anchor when rendered in a browser, with built-in JavaScript functionality for performance. For more information, consult the [API reference for `<Link />`](/docs/gatsby-link/).
+
+### Additional resources
+
+- [Linking Between Pages guide](/docs/linking-between-pages)
+- [Gatsby Link API](/docs/gatsby-link)
 
 ## Creating a layout component
 

examples/recipe-createPage/README.md

@@ -1,3 +1,5 @@
 # createPage Recipe
 
-This repo gives a simple example of creating pages programmatically from basic data
+This example shows how to create pages programmatically in a Gatsby site from basic data.
+
+Docs recipe: https://gatsbyjs.org/docs/recipes/pages-layouts#creating-pages-automatically

examples/recipe-createPage/package.json

@@ -1,7 +1,7 @@
 {
   "name": "recipe-create-page",
   "private": true,
-  "description": "A simple starter to get up and developing quickly with Gatsby",
+  "description": "A Gatsby docs recipe example on creating pages programmatically",
   "version": "0.1.0",
   "author": "@gatsbyjs",
   "dependencies": {
@@ -28,7 +28,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/gatsbyjs/gatsby-starter-default"
+    "url": "https://github.com/gatsbyjs/gatsby"
   },
   "bugs": {
     "url": "https://github.com/gatsbyjs/gatsby/issues"

examples/recipe-linking-between-pages/README.md

@@ -0,0 +1,34 @@
+# Linking Between Pages Recipe
+
+This example walks through linking between pages in a Gatsby site using Gatsby Link.
+
+Docs recipe: https://gatsbyjs.org/docs/recipes/pages-layouts#linking-between-pages
+
+## Install example
+
+Set up the project by installing dependencies in the directory:
+
+```
+cd recipe-linking-between-pages
+npm install
+```
+
+## Start the project
+
+```
+gatsby develop
+```
+
+## Run tests
+
+Run the Cypress integration tests to make sure everything still works.
+
+```
+npm test
+```
+
+This will start the Cypress app to inspect tests in more detail. You can also run them in a single-run for Continuous Integration (e.g. on a Github PR):
+
+```
+npm run test:ci
+```

examples/recipe-linking-between-pages/cypress.json

@@ -0,0 +1,4 @@
+{
+    "baseUrl": "http://localhost:8888/",
+    "fileServerFolder": "./src"
+  }

examples/recipe-linking-between-pages/cypress/fixtures/example.json

@@ -0,0 +1,5 @@
+{
+  "name": "Using fixtures to represent data",
+  "email": "hello@cypress.io",
+  "body": "Fixtures are a great way to mock data for responses to routes"
+}

examples/recipe-linking-between-pages/cypress/integration/linking.spec.js

@@ -0,0 +1,22 @@
+/// <reference types="cypress" />
+
+context('Linking between pages', () => {
+    it('should navigate to Contact after clicking a Gatsby link', () => {
+        cy.visit('http://localhost:8888')
+
+        cy.get('a').click()
+
+        cy.location('pathname').should('eq', '/contact/')
+
+        cy.get('main').should('include.text', 'Contact')
+    })
+    it('should link back to the homepage from Contact', () => {
+        cy.visit('http://localhost:8888/contact')
+
+        cy.get('a').click()
+
+        cy.location('pathname').should('eq', '/')
+
+        cy.get('main').should('include.text', 'What a world.')
+    })
+})

examples/recipe-linking-between-pages/cypress/plugins/index.js

@@ -0,0 +1,21 @@
+/// <reference types="cypress" />
+// ***********************************************************
+// This example plugins/index.js can be used to load plugins
+//
+// You can change the location of this file or turn off loading
+// the plugins file with the 'pluginsFile' configuration option.
+//
+// You can read more here:
+// https://on.cypress.io/plugins-guide
+// ***********************************************************
+
+// This function is called when a project is opened or re-opened (e.g. due to
+// the project's config changing)
+
+/**
+ * @type {Cypress.PluginConfig}
+ */
+module.exports = (on, config) => {
+  // `on` is used to hook into various events Cypress emits
+  // `config` is the resolved Cypress config
+}

examples/recipe-linking-between-pages/cypress/support/commands.js

@@ -0,0 +1,25 @@
+// ***********************************************
+// This example commands.js shows you how to
+// create various custom commands and overwrite
+// existing commands.
+//
+// For more comprehensive examples of custom
+// commands please read more here:
+// https://on.cypress.io/custom-commands
+// ***********************************************
+//
+//
+// -- This is a parent command --
+// Cypress.Commands.add("login", (email, password) => { ... })
+//
+//
+// -- This is a child command --
+// Cypress.Commands.add("drag", { prevSubject: 'element'}, (subject, options) => { ... })
+//
+//
+// -- This is a dual command --
+// Cypress.Commands.add("dismiss", { prevSubject: 'optional'}, (subject, options) => { ... })
+//
+//
+// -- This will overwrite an existing command --
+// Cypress.Commands.overwrite("visit", (originalFn, url, options) => { ... })

examples/recipe-linking-between-pages/cypress/support/index.js

@@ -0,0 +1,20 @@
+// ***********************************************************
+// This example support/index.js is processed and
+// loaded automatically before your test files.
+//
+// This is a great place to put global configuration and
+// behavior that modifies Cypress.
+//
+// You can change the location of this file or turn off
+// automatically serving support files with the
+// 'supportFile' configuration option.
+//
+// You can read more here:
+// https://on.cypress.io/configuration
+// ***********************************************************
+
+// Import commands.js using ES2015 syntax:
+import './commands'
+
+// Alternatively you can use CommonJS syntax:
+// require('./commands')

examples/recipe-linking-between-pages/gatsby-config.js

@@ -0,0 +1,7 @@
+module.exports = {
+  siteMetadata: {
+    title: `Linking Between Pages Recipe`,
+    description: `Example using Gatsby Link`,
+    author: `@gatsbyjs`,
+  },
+}

examples/recipe-linking-between-pages/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "recipe-links-between-pages",
+  "private": true,
+  "description": "A Gatsby docs recipe example on linking between pages",
+  "version": "0.1.0",
+  "author": "@gatsbyjs",
+  "dependencies": {
+    "gatsby": "^2.13.73",
+    "prop-types": "^15.7.2",
+    "react": "^16.9.0",
+    "react-dom": "^16.9.0",
+    "react-helmet": "^5.2.1"
+  },
+  "devDependencies": {
+    "cypress": "^4.0.2",
+    "gatsby-cypress": "^0.2.22",
+    "prettier": "^1.18.2",
+    "start-server-and-test": "^1.10.8"
+  },
+  "keywords": [
+    "gatsby"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "build": "gatsby build",
+    "develop": "gatsby develop",
+    "start": "npm run develop",
+    "serve": "gatsby serve",
+    "cy:open": "cypress open",
+    "cy:run": "cypress run",
+    "test-develop": "gatsby develop --port 8888",
+    "test": "CYPRESS_SUPPORT=y start-server-and-test test-develop http://localhost:8888 cy:open",
+    "test:ci": "start-server-and-test test-develop http://localhost:8888 cy:run"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gatsbyjs/gatsby"
+  },
+  "bugs": {
+    "url": "https://github.com/gatsbyjs/gatsby/issues"
+  }
+}

examples/recipe-linking-between-pages/src/pages/contact.js

@@ -0,0 +1,11 @@
+import React from "react"
+import { Link } from "gatsby"
+
+const ContactPage = () => (
+  <main>
+    <h1>Contact</h1>
+    <p><Link to="/">Go home</Link></p>
+  </main>
+)
+
+export default ContactPage

examples/recipe-linking-between-pages/src/pages/index.js

@@ -0,0 +1,11 @@
+import React from "react"
+import { Link } from "gatsby"
+
+const IndexPage = () => (
+  <main>
+      <h1>What a world.</h1>
+      <p><Link to="/contact/">Contact</Link></p>
+  </main>
+)
+
+export default IndexPage