feat(docs): Add official documentation for gatsby-plugin-transition-link and page transitions (#11423)

## Description
This PR adds a new article  about creating page transitions with `gatsby-plugin-transition-link`. It was based on issue #11333.

I also made the actual article a subsection underneath a general 'Adding Page Transitions' section and created a 'Adding page transitions with page-transitions' article (just a stub for now), since @calcsam mentioned in the issue that eventually documentation for that plugin will be added so it seems logical. 

I tried to make it detailed enough to cover most facets of the plugin, but also not too detailed as the documentation is already pretty good and it was mentioned that this should be slightly more beginner friendly.

This is my first PR contributing, so any help or criticism is appreciated :D

Here's how it looks:
![localhost_8000_docs_adding-page-transitions-with-plugin-transition-link_](https://user-images.githubusercontent.com/17508679/52004927-66ce4800-2496-11e9-8b3c-61ee7763340a.png)


## Related Issues
Resolves #11333

Author: alexieyizhe

docs/docs/adding-page-transitions-with-plugin-page-transitions.md

@@ -0,0 +1,12 @@
+---
+title: Adding Page Transitions with gatsby-plugin-page-transitions
+---
+
+`gatsby-plugin-page-transitions` is a Gatsby plugin that allows you to add page transitions to your Gatsby site.
+
+This guide will cover the setup and the various ways you can utilize this plugin.
+
+This is a stub. Help our community expand it.
+
+Please use the [Gatsby Style Guide](/docs/gatsby-style-guide/) to ensure your
+pull request gets accepted.

docs/docs/adding-page-transitions-with-plugin-transition-link.md

@@ -0,0 +1,169 @@
+---
+title: Adding Page Transitions with gatsby-plugin-transition-link
+---
+
+This guide will cover how to use `gatsby-plugin-transition-link` to animate transitions between pages on your Gatsby site.
+
+## Overview
+
+The `TransitionLink` component provides a way of describing a page transition via props on a Link component. It works with many animation libraries, like [react-pose](https://popmotion.io/pose/), [gsap](https://greensock.com/), [animejs](https://animejs.com/), and many others.
+
+Note that currently, as the plugin is based on link navigation, transitions when navigating with the browser buttons are not supported.
+
+For other page transition options, see the [overview on adding page animations](/docs/adding-page-transitions).
+
+## Getting started
+
+First, install the plugin:
+
+```shell
+npm install --save gatsby-plugin-transition-link
+```
+
+Make sure to add the plugin to your `gatsby-config.js`:
+
+```javascript:title=gatsby-config.js
+module.exports = {
+    plugins: [
+      `gatsby-plugin-transition-link`
+    ]
+];
+```
+
+Finally, import the `TransitionLink` component wherever you want to use it:
+
+```javascript
+import TransitionLink from "gatsby-plugin-transition-link"
+```
+
+## Predefined transitions
+
+You can use the `AniLink` component to add page transitions without having to define your own custom transitions. It's a wrapper around `TransitionLink` that provides 4 predefined transitions: `fade`, `swipe`, `cover`, and `paintDrip`. You can preview them at [this demo site](https://gatsby-plugin-transition-link.netlify.com/).
+
+To use AniLink, you will need to install the `gsap` animation library:
+
+```shell
+npm install --save gsap
+```
+
+Then, import the AniLink component:
+
+```javascript
+import AniLink from "gatsby-plugin-transition-link/AniLink"
+```
+
+Finally, make sure you provide your desired animation's name as a blank prop to `AniLink`:
+
+```javascript
+<AniLink paintDrip to="page-4">
+  Go to Page 4
+</AniLink>
+```
+
+Options like transition duration, direction, and more are customizable with props. See [the documentation of AniLink](https://transitionlink.tylerbarnes.ca/docs/anilink/) for more details.
+
+## Custom transitions
+
+You have two main methods of creating page transitions:
+
+1. Use the `trigger` function defined in your `exit`/`entry` prop. More details in the '[Using the `trigger` function](#using-the-trigger-function)' subsection.
+2. Use the props passed by `TransitionLink` to define your transitions. More details in the '[Using passed props](#using-passed-props)' subsection.
+
+Additionally, you can specify a number of props and options on the `TransitionLink` component, like `length`, `delay`, and more. For more options and details, see [the documentation of TransitionLink](https://transitionlink.tylerbarnes.ca/docs/transitionlink/). For further examples of usage, visit the [plugin's Github repository.](https://github.com/TylerBarnes/gatsby-plugin-transition-link)
+
+#### Using the trigger function
+
+You can specify a `trigger` function that will handle the animation. This is useful for _imperative_ animation libaries like [animejs](https://animejs.com/) or [GSAP](https://greensock.com/gsap) that specify animations with function calls.
+
+```javascript
+<TransitionLink
+  exit={{
+    length: length,
+    // highlight-next-line
+    trigger: ({ exit, node }) =>
+      this.someCustomDefinedAnimation({ exit, node, direction: "out" }),
+  }}
+  entry={{
+    length: 0,
+    // highlight-next-line
+    trigger: ({ exit, node }) =>
+      this.someCustomDefinedAnimation({ exit, node, direction: "in" }),
+  }}
+  {...props}
+>
+  {props.children}
+</TransitionLink>
+```
+
+#### Using passed props
+
+The exiting and entering pages/templates involved in the transition will receive props indicating the current transition status, as well as the `exit` or `enter` props defined on the `TransitionLink`.
+
+```javascript
+const PageOrTemplate = ({ children, transitionStatus, entry, exit }) => {
+  console.log(transitionStatus, entry, exit)
+  return <div className={transitionStatus}>{children}</div>
+}
+```
+
+You can combine these props with a _declarative_ state-based animation libraries like [react-pose](https://popmotion.io/pose/) or [react-spring](http://react-spring.surge.sh/) to specify transitions for exiting and entering a page.
+
+If you want to access these props in one of your components instead of a page/template, you should wrap your component in the `TransitionState` component. This component takes a function that will have access to the same props as above, which you can then use in your component.
+
+Here's an example using `TransitionState` and `react-pose` to trigger enter/exit transitions for a `Box` component.
+
+```javascript
+import { TransitionLink } from "gatsby-plugin-transition-link"
+
+const Box = posed.div({
+  hidden: { opacity: 0 },
+  visible: { opacity: 1 },
+})
+
+<TransitionState>
+      {({ transitionStatus, exit, enter }) => {
+        console.log('exit object is', exit)
+        console.log('enter object is', enter)
+
+        return (
+            <Box
+              className="box"
+              pose={
+                ['entering', 'entered'].includes(transitionStatus)
+                  ? 'visible'
+                  : 'hidden'
+              }
+            />
+        )
+      }}
+</TransitionState>
+```
+
+Now, the `Box` component will be aware of the transition status of the page it's a child of, and it will fade in/out accordingly.
+
+## Excluding elements from page transitions
+
+You may want to have elements on a page that persist throughout the page transition (_ex. a site-wide header_). This can be accomplished by wrapping elements in the `TransitionPortal` component.
+
+```javascript
+import { TransitionPortal } from "gatsby-plugin-transition-link"
+```
+
+```javascript
+<TransitionPortal>
+  <SomeComponent>
+    This component will sit on top of both pages, and persist through page
+    transitions.
+  </SomeComponent>
+</TransitionPortal>
+```
+
+As always, check out [the `TransitionPortal` docs](https://transitionlink.tylerbarnes.ca/docs/transitionportal/) for more information about `TransitionPortal`.
+
+## Further reading
+
+- [Official documentation](https://transitionlink.tylerbarnes.ca/docs/)
+- [Source code for plugin](https://github.com/TylerBarnes/gatsby-plugin-transition-link)
+- [Demo site](https://gatsby-plugin-transition-link.netlify.com/)
+- [Blog post: 'Per-Link Gatsby page transitions with TransitionLink'](https://www.gatsbyjs.org/blog/2018-12-04-per-link-gatsby-page-transitions-with-transitionlink/)
+- [Using transition-link with react-spring](https://github.com/TylerBarnes/gatsby-plugin-transition-link/issues/34)

docs/docs/adding-page-transitions.md

@@ -0,0 +1,8 @@
+---
+title: Adding Page Transitions
+overview: true
+---
+
+Page transitions give users a better experience when navigating between pages. There are a number of ways to add them to your Gatsby site.
+
+[[guidelist]]

www/src/data/sidebars/doc-links.yaml

@@ -253,6 +253,13 @@
           link: /docs/adding-an-rss-feed/
         - title: Linking Between Pages
           link: /docs/linking-between-pages/
+        - title: Adding Page Transitions
+          link: /docs/adding-page-transitions/
+          items:
+            - title: Adding Page Transitions with gatsby-plugin-transition-link
+              link: /docs/adding-page-transitions-with-plugin-transition-link/
+            - title: Adding Page Transitions with gatsby-plugin-page-transitions*
+              link: /docs/adding-page-transitions-with-plugin-page-transitions/
         - title: Making Your Site Accessible
           link: /docs/making-your-site-accessible
         - title: Routing