[docs] reorganize Tutorials, Rename Docs Sections (gatsbyjs#14071)

* move advanced tutorials to tutorials * update sidebar titles for IA reorg * adjust wording for advanced tutorials * update links for advanced tutorials * move source plugin tutorial back to docs * add a heading to beginner tutorials section * add link to advanced tutorials from part 8
ajordanow · May 22, 2019 · 24d7e5f · 24d7e5f
1 parent 4f53fd5
commit 24d7e5f
Show file tree

Hide file tree

Showing 27 changed files with 101 additions and 54 deletions.
diff --git a/docs/blog/2018-05-31-open-sourcing-gatsby-workshops/index.md b/docs/blog/2018-05-31-open-sourcing-gatsby-workshops/index.md
@@ -28,8 +28,8 @@ And that's just one page of notes (there were many more). The biggest takeaways
 
 People are interested in tutorials that go beyond the basic [Tutorial](/tutorial/), so we created three new tutorials:
 
-- [WordPress Source Plugin Tutorial](/docs/wordpress-source-plugin-tutorial/)
-- [Adding Images to a WordPress Site](/docs/image-tutorial/)
+- [WordPress Source Plugin Tutorial](/tutorial/wordpress-source-plugin-tutorial/)
+- [Adding Images to a WordPress Site](/tutorial/image-tutorial/)
 - [Creating a Source Plugin](/docs/creating-a-source-plugin/)
 
 ## Why you might want to host a workshop

diff --git a/docs/blog/2018-11-07-gatsby-for-apps/index.md b/docs/blog/2018-11-07-gatsby-for-apps/index.md
@@ -233,7 +233,7 @@ We can't wait to see what you build.
 [case-study]: https://developers.google.com/web/showcase/2017/twitter
 [gatsby-graphql]: /docs/querying-with-graphql/
 [gatsby-without-graphql]: /docs/using-gatsby-without-graphql/
-[authentication-data]: /docs/authentication-tutorial/
+[authentication-data]: /tutorial/authentication-tutorial/
 [client-only-routes]: /docs/building-apps-with-gatsby/#client-only-routes--user-authentication
 [create-react-app]: https://facebook.github.io/create-react-app/
 [react-dom-render-to-string]: https://reactjs.org/docs/react-dom-server.html#rendertostring
@@ -242,7 +242,7 @@ We can't wait to see what you build.
 [react-context]: https://reactjs.org/docs/context.html
 [react-lifecycle-methods]: https://reactjs.org/docs/state-and-lifecycle.html
 [gatsby-unstructured]: /blog/2018-10-25-unstructured-data/
-[authentication-tutorial]: /docs/authentication-tutorial/
+[authentication-tutorial]: /tutorial/authentication-tutorial/
 [using-gatsby-image]: https://using-gatsby-image.gatsbyjs.org/
 [traced-svg]: https://using-gatsby-image.gatsbyjs.org/traced-svg/
 [gatsby-plugin-offline]: /packages/gatsby-plugin-offline/

diff --git a/docs/blog/2019-02-27-reactiflux-q-and-a/index.md b/docs/blog/2019-02-27-reactiflux-q-and-a/index.md
@@ -163,7 +163,7 @@ It's a great place to get started. That said, I'd also encourage to check out [a
 
 So--however you implement authentication into a React application can be followed similarly with a Gatsby application, because a Gatsby app is a React application.
 
-We do have [a guide/tutorial written here](/docs/authentication-tutorial/) which many have found helpful. Shameless shout out to my little side-project (just a demo, not a real product!) [gatsby-mail](https://github.com/dschau/gatsby-mail) which has user authentication (via React context) as well.
+We do have [a guide/tutorial written here](/tutorial/authentication-tutorial/) which many have found helpful. Shameless shout out to my little side-project (just a demo, not a real product!) [gatsby-mail](https://github.com/dschau/gatsby-mail) which has user authentication (via React context) as well.
 
 Check it out, and hope it's helpful!
 

diff --git a/docs/blog/2019-04-06-security-for-modern-web-frameworks/index.md b/docs/blog/2019-04-06-security-for-modern-web-frameworks/index.md
@@ -86,7 +86,7 @@ Fortunately, this is an easy fix using [environment variables](/docs/environment
 
 ### Private Content
 
-Private content, whether dynamic or static, is another solution and is well documented in Gatsby's [authentication tutorial](/docs/authentication-tutorial/#security-notice).
+Private content, whether dynamic or static, is another solution and is well documented in Gatsby's [authentication tutorial](/tutorial/authentication-tutorial/#security-notice).
 
 **TL;DR:** Authenticate users using JSON Web Tokens(JWTs) and dynamically render pages only to authorized users. Any API calls that need to be made in order to fetch content can use the user's JWT and be verified by the API. If you need to access a third party API, any API keys can be stored securely by your API which is securely authenticated to using the JWT.
 
@@ -140,6 +140,6 @@ Now go make awesome Gatsby sites that are completely secure! For more informatio
 
 - **Secure APIs**: For information on securing all APIs (authenticated or not) checkout the [Rest Secutiry Cheat Sheet](https://github.com/OWASP/CheatSheetSeries/blob/master/cheatsheets/REST_Security_Cheat_Sheet.md) from OWASP.
 
-- **[Gatsby Authentication Tutorial](/docs/authentication-tutorial/#security-notice)**
+- **[Gatsby Authentication Tutorial](/tutorial/authentication-tutorial/#security-notice)**
 
 **Disclaimer**: The author does not claim to be a security expert. He is a developer who cares about security and has some experience. This post might contain incomplete or inaccurate information. It is your responsibility to properly secure your sites.
diff --git a/docs/docs/advanced-tutorials.md b/docs/docs/advanced-tutorials.md
diff --git a/docs/docs/api-reference.md b/docs/docs/api-reference.md
@@ -1,5 +1,5 @@
 ---
-title: API Reference
+title: Gatsby API Reference
 overview: true
 ---
 

diff --git a/docs/docs/building-a-site-with-authentication.md b/docs/docs/building-a-site-with-authentication.md
@@ -19,9 +19,9 @@ You must know how to set up a basic Gatsby project. If you need to, check the
 
 To create a common authentication workflow, you can usually follow these steps:
 
-- [Create client-only routes](/docs/authentication-tutorial/#creating-client-only-routes),
+- [Create client-only routes](/tutorial/authentication-tutorial/#creating-client-only-routes),
   to tell Gatsby which routes should be rendered on demand
-- [Wrap private content in a PrivateRoute component](/docs/authentication-tutorial/#controlling-private-routes),
+- [Wrap private content in a PrivateRoute component](/tutorial/authentication-tutorial/#controlling-private-routes),
   to check if a user is authenticated or not, therefore rendering the content or
   redirecting to another page (usually, the login page)
 
@@ -55,7 +55,7 @@ const PrivateRoute = ({ component: Component, ...rest }) => {
 
 If you want more information about authenticated areas with Gatsby, this (non-exhaustive list) may help:
 
-- [Making a site with user authentication](/docs/authentication-tutorial), a Gatsby advanced tutorial
+- [Making a site with user authentication](/tutorial/authentication-tutorial), a Gatsby advanced tutorial
 - [Gatsby repo simple auth example](https://github.com/gatsbyjs/gatsby/tree/master/examples/simple-auth)
 - [A Gatsby email _application_](https://github.com/DSchau/gatsby-mail), using React Context API to handle authentication
 - [The Gatsby store for swag and other Gatsby goodies](https://github.com/gatsbyjs/store.gatsbyjs.org)

diff --git a/docs/docs/centralizing-your-sites-navigation.md b/docs/docs/centralizing-your-sites-navigation.md
@@ -260,5 +260,5 @@ If you have made it this far, good job! You can now add new site links to your w
 
 Be sure to check out more documentation for further in-depth examples and guides on achieving tasks using Gatsby.
 
-- [Authentication in Gatsby](/docs/authentication-tutorial/)
-- [E-commerce in Gatsby](/docs/ecommerce-tutorial/)
+- [Authentication in Gatsby](/tutorial/authentication-tutorial/)
+- [E-commerce in Gatsby](/tutorial/ecommerce-tutorial/)
diff --git a/docs/docs/guides.md b/docs/docs/guides.md
@@ -1,8 +1,8 @@
 ---
-title: Guides
+title: Reference Guides
 overview: true
 ---
 
-Dive deeper into different topics around building with Gatsby, like sourcing data, deployment, and more.
+Dive deeper into different topics around building with Gatsby, like sourcing data, building and styling pages, deployment, and more. While the [tutorials](/tutorial/) are step-by-step instructions, reference guides are resources about the various Gatsby development techniques.
 
 <GuideList slug={props.slug} />
diff --git a/docs/docs/pixabay-source-plugin-tutorial.md b/docs/docs/pixabay-source-plugin-tutorial.md
@@ -1,5 +1,5 @@
 ---
-title: "Pixabay Source Plugin Tutorial"
+title: "Pixabay Image Source Plugin Tutorial"
 ---
 
 Creating your own source plugin.

diff --git a/docs/docs/preoptimizing-images.md b/docs/docs/preoptimizing-images.md
@@ -2,7 +2,7 @@
 title: Preoptimizing your Images
 ---
 
-Gatsby ships with excellent image optimization capabilities (see the [Image Tutorial](/docs/image-tutorial/) for more info). However, this image optimization can come with a cost. It can be fairly CPU intensive, and in some cases may lead to long build times. As a means of debugging and perhaps improving your overall build performance, it _may_ be helpful to pre-optimize your (extremely large) images.
+Gatsby ships with excellent image optimization capabilities (see the [Image Tutorial](/tutorial/image-tutorial/) for more info). However, this image optimization can come with a cost. It can be fairly CPU intensive, and in some cases may lead to long build times. As a means of debugging and perhaps improving your overall build performance, it _may_ be helpful to pre-optimize your (extremely large) images.
 
 First, some context. `gatsby-plugin-sharp` ships with a `fluid` option which will attempt to create five images intended to map to various screen resolutions. Producing multiple images ensures that your images are ready and optimized for phone displays, desktop displays, and everything in between. This plugin receives a non-optimized image and produces optimized images for _all_ of your users and devices. Magic!
 

diff --git a/docs/tutorial/advanced-tutorials.md b/docs/tutorial/advanced-tutorials.md
@@ -0,0 +1,7 @@
+---
+title: Advanced Tutorials
+---
+
+There are many use cases for Gatsby, from the very common "happy paths" to more specific and complex integrations. With the advanced Gatsby tutorials, learn about topics that go beyond [the basics](/tutorial/) and gain development superpowers.
+
+<GuideList slug={props.slug} />
diff --git a/docs/docs/authentication-tutorial.md → docs/tutorial/authentication-tutorial.md b/docs/docs/authentication-tutorial.md → docs/tutorial/authentication-tutorial.md
diff --git a/docs/docs/ecommerce-tutorial/index.md → docs/tutorial/ecommerce-tutorial/index.md b/docs/docs/ecommerce-tutorial/index.md → docs/tutorial/ecommerce-tutorial/index.md
@@ -518,7 +518,7 @@ You can call `redirectToCheckout()` providing an array of SKUs and their quantit
 
 ## Custom: Fully custom checkout flow (requires backend component)
 
-Stripe Checkout is currently in beta. You can sign up to receive updates on the [Stripe website](https://stripe.com/docs/payments/checkout). In the meantime, if you're looking to build more custom checkout flows, you can set up a simple function that your Gatsby project can POST to in order to handle the payment. See the previous version of [this tutorial](https://github.com/gatsbyjs/gatsby/blob/6b3c08782d0898719b61181638b6a0967da49dd6/docs/docs/ecommerce-tutorial/index.md) for detailed steps.
+Stripe Checkout is currently in beta. You can sign up to receive updates on the [Stripe website](https://stripe.com/docs/payments/checkout). In the meantime, if you're looking to build more custom checkout flows, you can set up a simple function that your Gatsby project can POST to in order to handle the payment. See the previous version of [this tutorial](https://github.com/gatsbyjs/gatsby/blob/6b3c08782d0898719b61181638b6a0967da49dd6/docs/tutorial/ecommerce-tutorial/index.md) for detailed steps.
 
 # Testing Payments
 

diff --git a/...merce-tutorial/stripe-public-test-key.png → ...merce-tutorial/stripe-public-test-key.png b/...merce-tutorial/stripe-public-test-key.png → ...merce-tutorial/stripe-public-test-key.png
diff --git a/docs/docs/image-tutorial.md → docs/tutorial/image-tutorial.md b/docs/docs/image-tutorial.md → docs/tutorial/image-tutorial.md
diff --git a/docs/tutorial/index.md b/docs/tutorial/index.md
@@ -1,22 +1,30 @@
 ---
-title: Gatsby.js Tutorial
+title: Gatsby.js Tutorials
 ---
 
 Welcome to Gatsby! We’re glad you’re here. The goal of this tutorial is to guide you through setting up and deploying your first Gatsby site using a starter template. As we walk through that process, we’ll introduce some more general web development topics, and go over the underlying structure of a Gatsby site.
 
 > The full tutorial is intended to be as accessible as possible to people without much web development experience (yet!) — no need to be an expert. If you prefer to jump straight to code, feel free to skip the step-by-step tutorial and see the [quick start](/docs/quick-start/) page.
 
+## Gatsby fundamentals
+
 0.  [Set Up Your Development Environment](/tutorial/part-zero/): We'll introduce you to core technologies that power Gatsby, and guide you through setting up your development environment.
 1.  [Get to know Gatsby building blocks](/tutorial/part-one/): Starting new projects, developing, and deploying sites.
 1.  [Introduction to using CSS in Gatsby](/tutorial/part-two/): Explore libraries like Typography.js and CSS Modules.
 1.  [Building nested layouts in Gatsby](/tutorial/part-three/): Layouts are sections of your site that are reused across multiple pages like headers and footers.
 
-## Advanced tutorials
+## Intermediate tutorials
 
-In these advanced tutorials, you'll learn how to pull data from almost anywhere into your Gatsby site with GraphQL.
+In these intermediate tutorials, you'll learn how to pull data from almost anywhere into your Gatsby site with GraphQL.
 
 4.  [Querying for data in a blog](/tutorial/part-four/): Create a blog and use a GraphQL query to pull your site title into the blog header.
 5.  [Source plugins and rendering queried data](/tutorial/part-five/): Use a source plugin to pull Markdown blog posts into your site and create an index page with a list of blog posts.
 6.  [Transformer plugins](/tutorial/part-six/): Use a transformer plugin to transform your Markdown blog posts into a form the blog can render.
 7.  [Programmatically create pages from data](/tutorial/part-seven/): Learn how to programmatically create a set of pages for your blog posts.
 8.  [Preparing a site to go live](/tutorial/part-eight/): Learn how to audit your site for performance and best practices for accessibility, SEO, and more.
+
+## Advanced tutorials
+
+There are many use cases for Gatsby, some which aren't covered in beginner or advanced tutorials to keep you focused while learning. The advanced Gatsby tutorials section is a collection of advanced use cases shown step-by-step, such as using source plugins for images and CMS content.
+
+Go deeper with the [advanced Gatsby tutorials](/tutorial/advanced-tutorials/).
diff --git a/docs/tutorial/part-eight/index.md b/docs/tutorial/part-eight/index.md
@@ -220,7 +220,9 @@ Lighthouse is a great tool for site improvements and learning -- Continue lookin
 
 ## That's all, folks
 
-Well, not quite. Just for this tutorial. This is just the beginning. Keep going!
+Well, not quite; just for this tutorial. There are also [Advanced Tutorials](/tutorial/advanced-tutorials/) to check out for more guided use cases.
+
+This is just the beginning. Keep going!
 
 - Did you build something cool? Share it on Twitter, tag [#buildwithgatsby](https://twitter.com/search?q=%23buildwithgatsby), and [@mention us](https://twitter.com/gatsbyjs)!
 - Did you write a cool blog post about what you learned? Share that, too!

diff --git a/.../docs/wordpress-source-plugin-tutorial.md → ...orial/wordpress-source-plugin-tutorial.md b/.../docs/wordpress-source-plugin-tutorial.md → ...orial/wordpress-source-plugin-tutorial.md
@@ -6,7 +6,7 @@ title: "WordPress Source Plugin Tutorial"
 
 ### What this tutorial covers:
 
-In this tutorial, you will install the `gatsby-source-wordpress` plugin in order to pull blog and image data from a WordPress install into your Gatsby site and render that data. This [Gatsby + WordPress demo site](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-wordpress) shows you the source code for an example site similar to what you’re going to be building in this tutorial, although it’s missing the cool images you’ll be adding in the next part of this tutorial, [Adding Images to a WordPress Site](/docs/image-tutorial/). :D
+In this tutorial, you will install the `gatsby-source-wordpress` plugin in order to pull blog and image data from a WordPress install into your Gatsby site and render that data. This [Gatsby + WordPress demo site](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-wordpress) shows you the source code for an example site similar to what you’re going to be building in this tutorial, although it’s missing the cool images you’ll be adding in the next part of this tutorial, [Adding Images to a WordPress Site](/tutorial/image-tutorial/). :D
 
 #### But do you prefer GraphQL?
 

diff --git a/docs/docs/writing-documentation-with-docz.md → ...torial/writing-documentation-with-docz.md b/docs/docs/writing-documentation-with-docz.md → ...torial/writing-documentation-with-docz.md
diff --git a/www/gatsby-node.js b/www/gatsby-node.js
@@ -266,6 +266,37 @@ exports.createPages = ({ graphql, actions, reporter }) => {
     isPermanent: true,
   })
 
+  createRedirect({
+    fromPath: `/docs/advanced-tutorials/`,
+    toPath: `/tutorial/advanced-tutorials/`,
+    isPermanent: true,
+  })
+  createRedirect({
+    fromPath: `/docs/authentication-tutorial/`,
+    toPath: `/tutorial/authentication-tutorial/`,
+    isPermanent: true,
+  })
+  createRedirect({
+    fromPath: `/docs/ecommerce-tutorial/`,
+    toPath: `/tutorial/ecommerce-tutorial/`,
+    isPermanent: true,
+  })
+  createRedirect({
+    fromPath: `/docs/image-tutorial/`,
+    toPath: `/tutorial/image-tutorial/`,
+    isPermanent: true,
+  })
+  createRedirect({
+    fromPath: `/docs/wordpress-source-plugin-tutorial/`,
+    toPath: `/tutorial/wordpress-source-plugin-tutorial/`,
+    isPermanent: true,
+  })
+  createRedirect({
+    fromPath: `/docs/writing-documentation-with-docz/`,
+    toPath: `/tutorial/writing-documentation-with-docz/`,
+    isPermanent: true,
+  })
+
   createRedirect({
     fromPath: `/docs/behind-the-scenes/`,
     toPath: `/docs/gatsby-internals/`,

diff --git a/www/src/components/guide-list.js b/www/src/components/guide-list.js
@@ -1,9 +1,10 @@
 import React from "react"
 
 import docsHierarchy from "../data/sidebars/doc-links.yaml"
+import tutorialHierarchy from "../data/sidebars/tutorial-links.yaml"
 
 // Search through tree, which may be 2, 3 or more levels deep
-const childItemsBySlug = (docsHierarchy, slug) => {
+const childItemsBySlug = (docsHierarchy, tutorialHierarchy, slug) => {
   let result
 
   const iter = a => {
@@ -15,11 +16,13 @@ const childItemsBySlug = (docsHierarchy, slug) => {
   }
 
   docsHierarchy.some(iter)
+  tutorialHierarchy.some(iter)
   return result && result.items
 }
 
 const GuideList = ({ slug }) => {
-  const subitemsForPage = childItemsBySlug(docsHierarchy, slug) || []
+  const subitemsForPage =
+    childItemsBySlug(docsHierarchy, tutorialHierarchy, slug) || []
   const subitemList = subitemsForPage.map((subitem, i) => (
     <li key={i}>
       <a href={subitem.link}>{subitem.title}</a>

diff --git a/www/src/components/navigation-mobile.js b/www/src/components/navigation-mobile.js
@@ -85,7 +85,11 @@ const MobileNavigation = () => (
       }}
     >
       <MobileNavItem linkTo="/docs/" label="Docs" icon={DocsIcon} />
-      <MobileNavItem linkTo="/tutorial/" label="Tutorial" icon={TutorialIcon} />
+      <MobileNavItem
+        linkTo="/tutorial/"
+        label="Tutorials"
+        icon={TutorialIcon}
+      />
       <MobileNavItem linkTo="/plugins/" label="Plugins" icon={PluginsIcon} />
       <MobileNavItem linkTo="/blog/" label="Blog" icon={BlogIcon} />
       <MobileNavItem linkTo="/showcase/" label="Showcase" icon={ShowcaseIcon} />

diff --git a/www/src/components/navigation.js b/www/src/components/navigation.js
@@ -122,7 +122,7 @@ const Navigation = ({ pathname }) => {
         >
           <ul css={styles.ulContainer}>
             <NavItem linkTo="/docs/">Docs</NavItem>
-            <NavItem linkTo="/tutorial/">Tutorial</NavItem>
+            <NavItem linkTo="/tutorial/">Tutorials</NavItem>
             <NavItem linkTo="/plugins/">Plugins</NavItem>
             <NavItem linkTo="/features/">Features</NavItem>
             <NavItem linkTo="/blog/">Blog</NavItem>

diff --git a/www/src/data/sidebars/doc-links.yaml b/www/src/data/sidebars/doc-links.yaml
@@ -13,7 +13,7 @@
       link: /starters/
     - title: Awesome Gatsby Resources
       link: /docs/awesome-gatsby/
-    - title: Guides
+    - title: Reference Guides
       link: /docs/guides/
       items:
         - title: Preparing Your Environment
@@ -174,7 +174,7 @@
                   link: /docs/creating-a-transformer-plugin/
                 - title: Submit to Plugin Library
                   link: /contributing/submit-to-plugin-library/
-                - title: Pixabay Source Plugin Tutorial
+                - title: Pixabay Image Source Plugin Tutorial
                   link: /docs/pixabay-source-plugin-tutorial/
                 - title: Remark Plugin Tutorial
                   link: /docs/remark-plugin-tutorial/
@@ -335,7 +335,7 @@
           items:
             - title: Creating Prefixed 404 Pages for Different Languages
               link: /docs/creating-prefixed-404-pages-for-different-languages/
-    - title: API Reference
+    - title: Gatsby API
       link: /docs/api-reference/
       items:
         - title: Gatsby Link
@@ -442,21 +442,6 @@
           link: /docs/build-caching/
         - title: Terminology
           link: /docs/gatsby-internals-terminology/
-    - title: Advanced Tutorials
-      link: /docs/advanced-tutorials/
-      items:
-        - title: Making a Site with User Authentication
-          link: /docs/authentication-tutorial/
-        - title: Making an e-commerce Gatsby Site
-          link: /docs/ecommerce-tutorial/
-        - title: Creating a Source Plugin
-          link: /docs/pixabay-source-plugin-tutorial/
-        - title: Using the WordPress Source Plugin
-          link: /docs/wordpress-source-plugin-tutorial/
-        - title: Adding Images to a WordPress Site
-          link: /docs/image-tutorial/
-        - title: Writing Documentation with Docz
-          link: /docs/writing-documentation-with-docz/
     - title: Using Gatsby Professionally
       link: /docs/using-gatsby-professionally/
       items:
@@ -528,6 +513,8 @@
           link: /docs/gatsby-vendor-partnership/
         - title: Agency Partnership Program
           link: /docs/gatsby-agency-partnership/
+    - title: Advanced Tutorials
+      link: /tutorial/advanced-tutorials/
     - title: Commands (Gatsby CLI)
       link: /docs/gatsby-cli/
     - title: Cheat Sheet