Merge pull request #4344 from strapi/improve-documentation-guides

Improve documentation guides

docs/.vuepress/config.js

@@ -126,6 +126,8 @@ module.exports = {
           children: [
             '/3.0.0-beta.x/guides/databases',
             '/3.0.0-beta.x/guides/deployment',
+            '/3.0.0-beta.x/guides/jwt-validation',
+            '/3.0.0-beta.x/guides/error-catching',
             '/3.0.0-beta.x/guides/webhooks',
           ],
         },

docs/3.0.0-beta.x/concepts/controllers.md

@@ -50,6 +50,8 @@ const { parseMultipartData, sanitizeEntity } = require('strapi-utils');
 #### `find`
 
 ```js
+const { sanitizeEntity } = require('strapi-utils');
+
 module.exports = {
   /**
    * Retrieve records.
@@ -60,9 +62,9 @@ module.exports = {
   async find(ctx) {
     let entities;
     if (ctx.query._q) {
-      entities = await service.search(ctx.query);
+      entities = await strapi.services.restaurant.search(ctx.query);
     } else {
-      entities = await service.find(ctx.query);
+      entities = await strapi.services.restaurant.find(ctx.query);
     }
 
     return entities.map(entity => sanitizeEntity(entity, { model }));
@@ -77,6 +79,8 @@ module.exports = {
 #### `findOne`
 
 ```js
+const { sanitizeEntity } = require('strapi-utils');
+
 module.exports = {
   /**
    * Retrieve a record.
@@ -85,7 +89,7 @@ module.exports = {
    */
 
   async findOne(ctx) {
-    const entity = await service.findOne(ctx.params);
+    const entity = await strapi.services.restaurant.findOne(ctx.params);
     return sanitizeEntity(entity, { model });
   },
 };
@@ -107,9 +111,9 @@ module.exports = {
 
   count(ctx) {
     if (ctx.query._q) {
-      return service.countSearch(ctx.query);
+      return strapi.services.restaurant.countSearch(ctx.query);
     }
-    return service.count(ctx.query);
+    return strapi.services.restaurant.count(ctx.query);
   },
 };
 ```
@@ -121,6 +125,8 @@ module.exports = {
 #### `create`
 
 ```js
+const { parseMultipartData, sanitizeEntity } = require('strapi-utils');
+
 module.exports = {
   /**
    * Create a record.
@@ -132,9 +138,9 @@ module.exports = {
     let entity;
     if (ctx.is('multipart')) {
       const { data, files } = parseMultipartData(ctx);
-      entity = await service.create(data, { files });
+      entity = await strapi.services.restaurant.create(data, { files });
     } else {
-      entity = await service.create(ctx.request.body);
+      entity = await strapi.services.restaurant.create(ctx.request.body);
     }
     return sanitizeEntity(entity, { model });
   },
@@ -148,6 +154,8 @@ module.exports = {
 #### `update`
 
 ```js
+const { parseMultipartData, sanitizeEntity } = require('strapi-utils');
+
 module.exports = {
   /**
    * Update a record.
@@ -159,9 +167,14 @@ module.exports = {
     let entity;
     if (ctx.is('multipart')) {
       const { data, files } = parseMultipartData(ctx);
-      entity = await service.update(ctx.params, data, { files });
+      entity = await strapi.services.restaurant.update(ctx.params, data, {
+        files,
+      });
     } else {
-      entity = await service.update(ctx.params, ctx.request.body);
+      entity = await strapi.services.restaurant.update(
+        ctx.params,
+        ctx.request.body
+      );
     }
 
     return sanitizeEntity(entity, { model });
@@ -176,6 +189,8 @@ module.exports = {
 #### `delete`
 
 ```js
+const { sanitizeEntity } = require('strapi-utils');
+
 module.exports = {
   /**
    * delete a record.
@@ -184,7 +199,7 @@ module.exports = {
    */
 
   async delete(ctx) {
-    const entity = await service.delete(ctx.params);
+    const entity = await strapi.services.restaurant.delete(ctx.params);
     return sanitizeEntity(entity, { model });
   },
 };

docs/3.0.0-beta.x/content-api/parameters.md

@@ -1,9 +1,9 @@
 # Parameters
 
-See the [parameters' concepts](../concepts/concepts.md#parameters) for details.
+See the [parameters' concepts](../concepts/parameters.md) for details.
 
 ::: warning
-By default, the filters can only be used from `find` endpoints generated by the Content Type Builder and the [CLI](../cli/CLI.md). If you need to implement a filters system somewhere else, read the [programmatic usage](../guides/parameters.md) section.
+By default, the filters can only be used from `find` endpoints generated by the Content Type Builder and the [CLI](../cli/CLI.md). If you need to implement a filter system somewhere else, read the [programmatic usage](../concepts/parameters.md) section.
 :::
 
 ## Available operators

docs/3.0.0-beta.x/getting-started/install-requirements.md

@@ -130,5 +130,5 @@ npm -v
 You can also use yarn if you want [here](https://yarnpkg.com/en/docs/getting-started) are the instructions to get started with it.
 
 ::: tip NEXT STEPS
-👏 Congrats, you are all set! Now that Node.js is installed you can continue with the [Quick start guide](/3.0.0-beta.x/getting-started/quick-start.html).
+👏 Congrats, you are all set! Now that Node.js is installed you can continue with the [Quick start guide](quick-start.md).
 :::

docs/3.0.0-beta.x/getting-started/introduction.md

@@ -1,4 +1,4 @@
-# Introduction 
+# Introduction
 
 Welcome to the open source [headless CMS](https://strapi.io) developers love.
 
@@ -6,15 +6,13 @@ Welcome to the open source [headless CMS](https://strapi.io) developers love.
 
 ### 👋 Welcome onboard!
 
-Users love Strapi because it is open source, MIT licensed, fully customizable and based on Node.js. Strapi lets you manage your content and distribute it anywhere. Strapi allows you to securely and privately serve your database of choice from your hosting and server of choice. 
+Users love Strapi because it is open source, MIT licensed, fully customizable and based on Node.js. Strapi lets you manage your content and distribute it anywhere. Strapi allows you to securely and privately serve your database from your hosting and server of choice.
 
 ### Get Started
 
 You are invited to get started using Strapi. You may explore Strapi by:
 
-1. A [Quick Start Guide](../getting-started/quick-start.html) for more intermediate to advanced developers.
+1. A [Quick Start Guide](quick-start.md) for more intermediate to advanced developers.
-2. A [Tutorial](../getting-started/quick-start-tutorial.html) for those who prefer a step-by-step introduction.
+2. A [Tutorial](quick-start-tutorial.md) for those who prefer a step-by-step introduction.
-
-When you're done getting started, we invite you to join our [community](https://strapi.io/community). 
-
 
+When you're done getting started, we invite you to join our [community](https://strapi.io/community).

docs/3.0.0-beta.x/getting-started/quick-start-tutorial.md

@@ -1,6 +1,6 @@
 # Tutorial
 
-This **tutorial** is written for developers to **teach and explain** a step-by-step introduction to Strapi. (The [Quick Start Guide](/3.0.0-beta.x/getting-started/quick-start.html) is a more concise **How-to** version.) This tutorial takes you through the beginning steps of how you start a project like **"FoodAdvisor"** ([Github](https://github.com/strapi/foodadvisor/))([Demo](https://foodadvisor.strapi.io/)).
+This **tutorial** is written for developers to **teach and explain** a step-by-step introduction to Strapi. (The [Quick Start Guide](quick-start.md) is a more concise **How-to** version.) This tutorial takes you through the beginning steps of how you start a project like **"FoodAdvisor"** ([Github](https://github.com/strapi/foodadvisor/))([Demo](https://foodadvisor.strapi.io/)).
 
 You get a good overview of the features developers love found in Strapi.
 
@@ -10,20 +10,13 @@ By following this tutorial, you install and create your first Strapi project.
 
 ::: tip NOTE
 
-You need to have **_Node.js and npm_** installed on your system before following these steps. If you do not have Node.js and npm installed (or are not sure), please visit our [Installation Requirements](/3.0.0-beta.x/getting-started/install-requirements.html).
+You need to have **_Node.js and npm_** installed on your system before following these steps. If you do not have Node.js and npm installed (or are not sure), please visit our [Installation Requirements](install-requirements.md).
 
 :::
 
 **Table of Contents**
 
-1. [Install Strapi and create project](/3.0.0-beta.x/getting-started/quick-start-tutorial.html#_1-install-strapi-and-create-a-project)
+[[toc]]
-2. [Create an Administrator and front-end User](/3.0.0-beta.x/getting-started/quick-start-tutorial.html#_2-create-an-adminstrator-and-front-end-user)
-3. [Create a new Content Type called, "Restaurant"](/3.0.0-beta.x/getting-started/quick-start-tutorial.html#_3-create-a-new-content-type-called-restaurant)
-4. [Create a new Content Type called, "Category"](/3.0.0-beta.x/getting-started/quick-start-tutorial.html#_4-create-a-new-content-type-called-category)
-5. [Create a new Group and Repeatable Field called, "Hours of Operations"](/3.0.0-beta.x/getting-started/quick-start-tutorial.html#_5-create-a-new-group-and-repeatable-field-called-hours-of-operation)
-6. [Manage and add content to the "Restaurant" Content Type](/3.0.0-beta.x/getting-started/quick-start-tutorial.html#_6-manage-and-add-content-to-a-restaurant-content-type)
-7. [Set Roles and Permissions](/3.0.0-beta.x/getting-started/quick-start-tutorial.html#_7-set-roles-and-permissions)
-8. [Consume the Content Type API](/3.0.0-beta.x/getting-started/quick-start-tutorial.html#_8-consume-the-content-type-api)
 
 ## 1. Install Strapi and create a project
 
@@ -140,7 +133,7 @@ Using the `--quickstart` flag installs Strapi using an [SQLite](https://www.sqli
 
 **Note:** An **SQLite** database is an excellent database to use for prototyping and _developing_ Strapi projects. **SQLite** is a light database that ports effortlessly to the other relational databases (**MySQL**, **PostgreSQL**, and **MariaDB**). It is recommended to **develop** with SQLite and to use another relational database (MySQL, PostgreSQL or MariaDB) in production.
 
-**Note:** If you would like to use **MongoDB** in production, you need to [install, run, and use MongoDB to develop your Strapi project (in development)](/3.0.0-beta.x/guides/databases.html#mongodb-installation).
+**Note:** If you would like to use **MongoDB** in production, you need to [install, run, and use MongoDB to develop your Strapi project (in development)](../guides/databases.md#mongodb-installation).
 :::
 
 You are now ready to create a new **Administrator** and new front-end **User**.
@@ -626,7 +619,7 @@ If you would like to see the route of any specific **Content Type**, you need to
 👏 Congratulations, you have now completed the **Strapi Getting Started Tutorial**. Where to go next?
 
 - Learn how to use Strapi with React ([Gatsby](https://blog.strapi.io/building-a-static-website-using-gatsby-and-strapi) or [Next.js](https://blog.strapi.io/strapi-next-setup/)) or Vue.js ([Nuxt.js](https://blog.strapi.io/cooking-a-deliveroo-clone-with-nuxt-vue-js-graphql-strapi-and-stripe-setup-part-1-7/)).
-- Read the [concepts](../concepts/concepts.html) to deep dive into Strapi
+- Read the **concepts** to deep dive into Strapi
 - Get help on [StackOverflow](https://stackoverflow.com/questions/tagged/strapi)
 - Read the [source code](https://github.com/strapi/strapi), [contribute](https://github.com/strapi/strapi/blob/master/CONTRIBUTING.md) or [give a star](https://github.com/strapi/strapi) on GitHub
 - Follow us on [Twitter](https://twitter.com/strapijs) to get the latest news

docs/3.0.0-beta.x/getting-started/quick-start.md

@@ -6,9 +6,9 @@ Get ready to get Strapi up and running in **less than 5 minutes** 🚀.
 <iframe width="853" height="480" src="https://www.youtube.com/embed/4m1wKzzfs-M" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
 </div>
 
-_For a step-by-step guide, please take a look at the [detailed tutorial](quick-start-tutorial.html)._
+_For a step-by-step guide, please take a look at the [detailed tutorial](quick-start-tutorial.md)._
 
-(Before continuing, please make sure [Node.js and npm are properly installed](install-requirements.html) on your machine. You can [install the Yarn v1.2.0+ package here](https://yarnpkg.com/en/).)
+(Before continuing, please make sure [Node.js and npm are properly installed](install-requirements.md) on your machine. You can [install the Yarn v1.2.0+ package here](https://yarnpkg.com/en/).)
 
 ## 1. Install Strapi and Create a new project
 
@@ -111,7 +111,7 @@ Here we are! The list of **restaurants** is accessible at [`http://localhost:133
 👏 Congratulations, you have now completed the **Strapi Quick Start**. Where to go next?
 
 - Learn how to use Strapi with React ([Gatsby](https://blog.strapi.io/building-a-static-website-using-gatsby-and-strapi) or [Next.js](https://blog.strapi.io/strapi-next-setup/)) or Vue.js ([Nuxt.js](https://blog.strapi.io/cooking-a-deliveroo-clone-with-nuxt-vue-js-graphql-strapi-and-stripe-setup-part-1-7/)).
-- Read the [concepts](../concepts/concepts.html) and do the [Tutorial](/3.0.0-beta.x/getting-started/quick-start-tutorial.html) to deep dive into Strapi.
+- Read the **concepts** and do the [Tutorial](quick-start-tutorial.md) to deep dive into Strapi.
 - Get help on [StackOverflow](https://stackoverflow.com/questions/tagged/strapi).
 - Read the [source code](https://github.com/strapi/strapi), [contribute](https://github.com/strapi/strapi/blob/master/CONTRIBUTING.md) or [give a star](https://github.com/strapi/strapi) on GitHub.
 - Follow us on [Twitter](https://twitter.com/strapijs) to get the latest news.

docs/3.0.0-beta.x/guides/databases.md

@@ -4,12 +4,12 @@ Strapi gives you the option to choose the most appropriate database for your pro
 **MariaDB**. The following documentation covers how to install these databases locally (for development purposes) and on various hosted or cloud server solutions (for staging or production purposes).
 
 :::note
-Deploying **Strapi** itself is covered in the [Deployment Guide](/3.0.0-beta.x/guides/deployment.html).
+Deploying **Strapi** itself is covered in the [Deployment Guide](deployment.md).
 :::
 
 ## SQLite Installation
 
-SQLite is the default ([Quick Start](/3.0.0-beta.x/getting-started/quick-start.html)) and recommended database to quickly create an app locally.
+SQLite is the default ([Quick Start](../getting-started/quick-start.md)) and recommended database to quickly create an app locally.
 
 ### Install SQLite locally
 
@@ -38,7 +38,7 @@ npx create-strapi-app my-project --quickstart
 This will create a new project and launch it in the browser.
 
 ::: note
-The [Quick Start Guide](/3.0.0-beta.x/getting-started/quick-start.html) is a complete step-by-step tutorial
+The [Quick Start Guide](../getting-started/quick-start.md) is a complete step-by-step tutorial
 :::
 
 ## MongoDB Installation
@@ -240,7 +240,7 @@ $ strapi develop
 
 ```
 
-You have successfully installed Strapi with MongoDB on your local development environment. You are now ready to [create your first user](/3.0.0-beta.x/getting-started/quick-start.html#_3-create-an-admin-user).
+You have successfully installed Strapi with MongoDB on your local development environment. You are now ready to [create your first user](../getting-started/quick-start.md#_3-create-an-admin-user).
 
 ---
 
@@ -248,7 +248,7 @@ You have successfully installed Strapi with MongoDB on your local development en
 
 Follow these steps to configure a local Strapi project to use a [MongoDB Atlas](https://www.mongodb.com/cloud/atlas) free 512 MB account in production. (Please see [MongoDB Atlas Documentation](https://docs.atlas.mongodb.com/getting-started/) if you have any questions.)
 
-- You must have already [created your Strapi project using MongoDB](/3.0.0-beta.x/guides/databases.html#install-strapi-locally-with-mongodb).
+- You must have already [created your Strapi project using MongoDB](databases.md#install-strapi-locally-with-mongodb).
 - You must have already created a [free MongoDB Atlas account](https://www.mongodb.com/cloud/atlas).
 
 #### 1. Log in to your account to create a **Project** and a **Cluster**
@@ -342,7 +342,7 @@ The above configuration will create a database called `strapi`, the _default dat
 :::
 
 ::: danger WARNING
-We recommend replacing sensitive (eg. "URI string" above) information in your database.json files before uploading your project to a public repository such as GitHub. For more information about using environment variables, please read [dynamic configurations](/3.0.0-beta.x/configurations/configurations.html#dynamic-configurations).
+We recommend replacing sensitive (eg. "URI string" above) information in your database.json files before uploading your project to a public repository such as GitHub. For more information about using environment variables, please read [dynamic configurations](../concepts/configurations.md#dynamic-configurations).
 
 :::
 

docs/3.0.0-beta.x/guides/deployment.md

@@ -3,7 +3,7 @@
 Strapi gives you many possible deployment options for your project or application. Strapi can be deployed on traditional hosting servers or services such as Heroku, AWS, Azure and others. The following documentation covers how to develop locally with Strapi and deploy Strapi with various hosting options.
 
 ::: note
-Deploying **databases** along with Strapi is covered in the [Databases Guide](/3.0.0-beta.x/guides/databases.html).
+Deploying **databases** along with Strapi is covered in the [Databases Guide](../guides/databases.md).
 :::
 
 ## Configuration
@@ -24,7 +24,7 @@ Update the `production` settings with the IP and domain name where the project w
 In case your database is not running on the same server, make sure that the environment of your production
 database (`./config/environments/production/database.json`) is set properly.
 
-If you are passing a number of configuration item values via environment variables which is always encouraged for production environment, read the section for [Dynamic Configuration](../configurations/configurations.md#dynamic-configurations). Here is an example:
+If you are passing a number of configuration item values via environment variables which is always encouraged for production environment, read the section for [Dynamic Configuration](../concepts/configurations.md#dynamic-configurations). Here is an example:
 
 **Path —** `./config/environments/production/server.json`.
 
@@ -95,11 +95,11 @@ strapi(/* {...} */).start();
 
 ### Advanced configurations
 
-If you want to host the administration on another server than the API, [please take a look at this dedicated section](../advanced/customize-admin.md#deployment).
+If you want to host the administration on another server than the API, [please take a look at this dedicated section](../admin-panel/deploy.md).
 
 ## Amazon AWS
 
-This is a step-by-step guide for deploying a Strapi project to [Amazon AWS EC2](https://aws.amazon.com/ec2/). This guide will connect to an [Amazon AWS RDS](https://aws.amazon.com/rds/) for managing and hosting the database. Optionally, this guide will show you how to connect host and serve images on [Amazon AWS S3](https://aws.amazon.com/s3/). Prior to starting this guide, you should have created a [Strapi project](/3.0.0-beta.x/getting-started/quick-start.html), to use for deploying on AWS.
+This is a step-by-step guide for deploying a Strapi project to [Amazon AWS EC2](https://aws.amazon.com/ec2/). This guide will connect to an [Amazon AWS RDS](https://aws.amazon.com/rds/) for managing and hosting the database. Optionally, this guide will show you how to connect host and serve images on [Amazon AWS S3](https://aws.amazon.com/s3/). Prior to starting this guide, you should have created a [Strapi project](../getting-started/quick-start.md), to use for deploying on AWS.
 
 ### Amazon AWS Install Requirement and creating an IAM non-root user
 
@@ -748,7 +748,7 @@ Your `Strapi` project has been installed on an **AWS EC2 instance** using **Ubun
 
 ## Digital Ocean
 
-This is a step-by-step guide for deploying a Strapi project to [Digital Ocean](https://www.digitalocean.com/). Databases can be on a [Digital Ocean Droplet](https://www.digitalocean.com/docs/droplets/) or hosted externally as a service. Prior to starting this guide, you should have created a [Strapi project](/3.0.0-beta.x/getting-started/quick-start.html).
+This is a step-by-step guide for deploying a Strapi project to [Digital Ocean](https://www.digitalocean.com/). Databases can be on a [Digital Ocean Droplet](https://www.digitalocean.com/docs/droplets/) or hosted externally as a service. Prior to starting this guide, you should have created a [Strapi project](../getting-started/quick-start.md).
 
 ### Digital Ocean Install Requirements
 
@@ -979,7 +979,7 @@ Command may disrupt existing ssh connections. Proceed with operation (y|n)? y
 Firewall is active and enabled on system startup
 ```
 
-Your Strapi project is now installed on your **Droplet**. You have a few more steps prior to being able to access Strapi and [create your first user](https://strapi.io/documentation/3.0.0-beta.x/getting-started/quick-start.html#_3-create-an-admin-user).
+Your Strapi project is now installed on your **Droplet**. You have a few more steps prior to being able to access Strapi and [create your first user](../getting-started/quick-start.md#_3-create-an-admin-user).
 
 You will next need to [install and configure PM2 Runtime](#install-and-configure-pm2-runtime).
 
@@ -1037,7 +1037,7 @@ pm2 start ecosystem.config.js
 
 `pm2` is now set-up to use an `ecosystem.config.js` to manage restarting your application upon changes. This is a recommended best practice.
 
-**OPTIONAL:** You may see your project and set-up your first administrator user, by [creating an admin user](https://strapi.io/documentation/3.0.0-beta.x/getting-started/quick-start.html#_3-create-an-admin-user).
+**OPTIONAL:** You may see your project and set-up your first administrator user, by [creating an admin user](../getting-started/quick-start.md#_3-create-an-admin-user).
 
 ::: note
 Earlier, `Port 1337` was allowed access for **testing and setup** purposes. After setting up **NGINX**, the **Port 1337** needs to have access **denied**.
@@ -1298,11 +1298,11 @@ Follow the instructions and return to your command line.
 
 #### 3. Create a new project (or use an existing one)
 
-Create a [new Strapi project](/3.0.0-beta.x/getting-started/quick-start.html) (if you want to deploy an existing project go to step 4).
+Create a [new Strapi project](../getting-started/quick-start.md) (if you want to deploy an existing project go to step 4).
 
 ::: warning NOTE
 
-If you plan to use **MongoDB** with your project, [refer to the create a Strapi project with MongoDB section of the documentation](/3.0.0-beta.x/guides/databases.html#install-mongodb-locally) then, jump to step 4.
+If you plan to use **MongoDB** with your project, [refer to the create a Strapi project with MongoDB section of the documentation](../guides/databases.md#install-mongodb-locally) then, jump to step 4.
 
 :::
 
@@ -1463,11 +1463,11 @@ npm install pg --save
 
 Please follow these steps the **deploy a Strapi app with MongoDB on Heroku**.
 
-You must have completed the [steps to use Strapi with MongoDB Atlas](/3.0.0-beta.x/guides/databases.html#install-on-atlas-mongodb-atlas) - through **4. Retrieve database credentials**.
+You must have completed the [steps to use Strapi with MongoDB Atlas](../guides/databases.md#install-on-atlas-mongodb-atlas) - through **4. Retrieve database credentials**.
 
 #### 1. Set environment variables
 
-When you [set-up your MongoDB Atlas database](/3.0.0-beta.x/guides/databases.html#install-on-atlas-mongodb-atlas) you noted a connection string. Similar to this:
+When you [set-up your MongoDB Atlas database](../guides/databases.md#install-on-atlas-mongodb-atlas) you noted a connection string. Similar to this:
 
 ```bash
 mongodb://paulbocuse:<password>@strapidatabase-shard-00-00-fxxx6c.mongodb.net:27017,strapidatabase-shard-00-01-fxxxc.mongodb.net:27017,strapidatabase-shard-00-02-fxxxc.mongodb.net:27017/test?ssl=true&replicaSet=strapidatabase-shard-0&authSource=admin&retryWrites=true&w=majority
@@ -1538,7 +1538,7 @@ heroku open
 
 If you see the Strapi Welcome page, you have correctly set-up, configured and deployed your Strapi project on Heroku. You will now need to set-up your `admin user` as the production database is brand-new (and empty).
 
-You can now continue with the [Tutorial - Creating an Admin User](/3.0.0-beta.x/getting-started/quick-start-tutorial.html#_3-create-an-admin-user), if you have any questions on how to proceed.
+You can now continue with the [Tutorial - Creating an Admin User](../getting-started/quick-start-tutorial.md#_3-create-an-admin-user), if you have any questions on how to proceed.
 
 ::: warning
 For security reasons, the Content Type Builder plugin is disabled in production. To update content structure, please make your changes locally and deploy again.

docs/3.0.0-beta.x/guides/error-catching.md

@@ -0,0 +1,89 @@
+# Error catching
+
+In this guide we will see how you can catch errors and send them to the Application Monitoring / Error Tracking Software you want.
+
+::: note
+In this example we will use [Sentry](https://sentry.io).
+:::
+
+## Create a middleware
+
+A [middleware](../concepts/middlewares.md) will be used in order to catch the errors which will then be sent to Sentry.
+
+- Create a `./middlewares/sentry/index.js` file.
+
+**Path —** `./middlewares/sentry/index.js`
+
+```js
+module.exports = strapi => {
+  return {
+    initialize() {
+      strapi.app.use(async (ctx, next) => {
+        await next();
+      });
+    },
+  };
+};
+```
+
+## Handle errors
+
+Here is the [Node.js client documentation](https://docs.sentry.io/platforms/node/)
+
+- Now add the logic that will catch errors.
+
+**Path —** `./middlewares/sentry/index.js`
+
+```js
+const Sentry = require('@sentry/node');
+Sentry.init({ dsn: 'https://<key>@sentry.io/<project>' });
+
+module.exports = strapi => {
+  return {
+    initialize() {
+      strapi.app.use(async (ctx, next) => {
+        try {
+          await next();
+        } catch (error) {
+          Sentry.captureException(error);
+          throw error;
+        }
+      });
+    },
+  };
+};
+```
+
+::: warning
+It's important to call `throw(error);` to avoid stopping the middleware stack. If you don't re-throw the error, it won't be handled by the Strapi's error formatter and the api will never respond to the client.
+:::
+
+## Configure the middleware
+
+Make sure your middleware is added at the end of the middleware stack.
+
+**Path —** `./config/middleware.json`
+
+```json
+{
+  ...
+    "after": [
+      "parser",
+      "router",
+      "sentry"
+    ]
+  }
+}
+```
+
+And finally you have to enable the middleware.
+
+**Path —** `./config/environments/**/middleware.json`
+
+```json
+{
+  "sentry": {
+    "enabled": true
+  }
+}
+```

docs/3.0.0-beta.x/guides/jwt-validation.md

@@ -0,0 +1,103 @@
+# JWT validation
+
+In this guide we will see how to validate a `JWT` (JSON Web Token) with a third party service.
+
+When you sign in with the authentication route `POST /auth/local`, Strapi generates a `JWT` which lets your users request your API as an authenticated one.
+
+```json
+{
+  "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZCI6MSwiaXNBZG1pbiI6dHJ1ZSwiaWF0IjoxNTcxODIyMDAzLCJleHAiOjE1NzQ0MTQwMDN9.T5XQGSDZ6TjgM5NYaVDbYJt84qHZTrtBqWu1Q3ShINw",
+  "user": {
+    "email": "admin@strapi.io",
+    "id": 1,
+    "username": "admin"
+  }
+}
+```
+
+These users are managed in the application's database and can be managed via the admin dashboard.
+
+We can now imagine you have a `JWT` that comes from [Auth0](https://auth0.com) and you want to make sure the `JWT` is correct before allowing the user to use the Strapi API endpoints.
+
+## Customize the JWT validation function
+
+We have to use the [customization concept](../concepts/customization.md) to update the function that validates the `JWT`. This feature is powered by the **Users & Permissions** plugin.
+
+Here is the file we will have to customize: [permission.js](https://github.com/strapi/strapi/blob/master/packages/strapi-plugin-users-permissions/config/policies/permissions.js)
+
+- We have to create a file that follows this path `./extensions/users-permissions/config/policies/permissions.js`.
+- You will have to add in this new file, the same content of the original one.
+
+Now we are ready to create our custom validation code.
+
+## Write our own logic
+
+First we have to define where write our code.
+
+```js
+const _ = require('lodash');
+
+module.exports = async (ctx, next) => {
+  let role;
+
+  if (ctx.request && ctx.request.header && ctx.request.header.authorization) {
+    try {
+      const { id, isAdmin = false } = await strapi.plugins[
+        'users-permissions'
+      ].services.jwt.getToken(ctx);
+
+      ...
+
+    } catch (err) {
+      // It will be there!
+
+      return handleErrors(ctx, err, 'unauthorized');
+    }
+```
+
+The `jwt.getToken` will throw an error if the token doesn't come from Strapi. So if it's not a Strapi `JWT` token, let's test if it's an Auth0 one.
+
+We will have to write our validation code before throwing an error.
+
+By using the [Auth0 get user profile](https://auth0.com/docs/api/authentication?http#get-user-info) documentation, you will verify a valid user matches with the current `JWT`
+
+```js
+const _ = require('lodash');
+const axios = require('axios');
+
+module.exports = async (ctx, next) => {
+  let role;
+
+  if (ctx.request && ctx.request.header && ctx.request.header.authorization) {
+    try {
+      const { id, isAdmin = false } = await strapi.plugins[
+        'users-permissions'
+      ].services.jwt.getToken(ctx);
+
+      ...
+
+    } catch (err) {
+      try {
+        const data = await axios({
+          method: 'post',
+          url: 'http://YOUR_DOMAIN/userinfo',
+          headers: {
+            Authorization: ctx.request.header.authorization
+          }
+        });
+
+        // if you want do more validation test
+        // feel free to add your code here.
+
+        return await next();
+      } catch (error) {
+        return handleErrors(ctx, new Error('Invalid token: Token did not match with Strapi and Auth0'), 'unauthorized');
+      }
+
+      return handleErrors(ctx, err, 'unauthorized');
+    }
+```
+
+::: warning
+In the code example we use `axios` you will have to install the dependency to make it work. You can choose another library if you prefer.
+:::

docs/3.0.0-beta.x/migration-guide/migration-guide-alpha.26-to-beta.md

@@ -196,7 +196,7 @@ You can leave all your files in `./config` unchanged but remove the `server.auto
 
 One of our main objectives for the `beta` is to make it easier and quicker to upgrade to more recent versions of Strapi. This is why moving forward, plugins will be located in the `node_modules` folder.
 
-[Read more](https://strapi.io/documentation/3.0.0-beta.x/concepts/concepts.html#files-structure)
+[Read more](../concepts/file-structure.md)
 
 Let's start by creating a new folder called `./extensions`. This folder needs to exist even if it's empty. You may use a `.gitkeep` file to ensure the folder isn't deleted from the repository (if it's empty) when cloning. [More details](https://davidwalsh.name/git-empty-directory).
 
@@ -495,7 +495,7 @@ The only difference is that the admin of a local plugin is ignored for the momen
 In the `beta`, we are introducing the `Core API`, which is replacing the templates that were generated before.
 
 Now when you create a new model your `controller` and `service` will be empty modules and will be used to override the default behaviors.
-Read more about [controllers](https://strapi.io/documentation/3.0.0-beta.x/guides/controllers.html) or [services](https://strapi.io/documentation/3.0.0-beta.x/guides/services.html)
+Read more about [controllers](../concepts/controllers.md) or [services](../concepts/services.md)
 
 To migrate, you will only have to delete the methods you haven't modified or created from your `controllers` and `services`
 

docs/3.0.0-beta.x/migration-guide/migration-guide-beta.15-to-beta.16.md

@@ -90,7 +90,7 @@ To make sure a Wysiwyg field stays the same when deploying, we introduced the `r
 
 ### Custom controllers and services
 
-If you are using [core services](../guides/services.md), you previously needed to call `result.toJSON()` or `result.toObject()` to get a plain javascript object. This is not the case anymore, you will now receive a simple object directly.
+If you are using [core services](../concepts/services.md), you previously needed to call `result.toJSON()` or `result.toObject()` to get a plain javascript object. This is not the case anymore, you will now receive a simple object directly.
 
 **Before**:
 
@@ -113,9 +113,9 @@ module.exports = {
 };
 ```
 
-The same modification was made to `strapi.query()`. Read more about **Queries** [here](../guides/queries.md).
+The same modification was made to `strapi.query()`. Read more about **Queries** [here](../concepts/queries.md).
 
-Keep in mind that if you are running custom ORM queries with Bookshelf or Mongoose you will still have to call `toJSON` or `toObject`. Check out this section about [custom queries](../guides/queries.html#api-reference).
+Keep in mind that if you are running custom ORM queries with Bookshelf or Mongoose you will still have to call `toJSON` or `toObject`. Check out this section about [custom queries](../concepts/queries.md#api-reference).
 
 ### Bootstrap function
 
@@ -167,7 +167,7 @@ module.exports = () => {};
 
 ### Custom hooks
 
-If you have custom [hooks](../advanced/hooks.md) in your project, the `initialize` function will not receive a callback anymore. You can either use an async function, return a promise or simply run a synchronous function.
+If you have custom [hooks](../concepts/hooks.md) in your project, the `initialize` function will not receive a callback anymore. You can either use an async function, return a promise or simply run a synchronous function.
 
 **Before**
 

docs/3.0.0-beta.x/plugin-development/backend-development.md

@@ -7,7 +7,7 @@ This section explains how the 'back-end part' of your plugin works.
 The plugin API routes are defined in the `./plugins/**/config/routes.json` file.
 
 ::: note
-Please refer to [router documentation](../guides/routing.md) for information.
+Please refer to [router documentation](../concepts/routing.md) for information.
 :::
 
 **Route prefix**
@@ -38,7 +38,7 @@ Please refer to the [CLI documentation](../cli/CLI.md) for more information.
 
 Controllers contain functions executed according to the requested route.
 
-Please refer to the [Controllers documentation](../guides/controllers.md) for more information.
+Please refer to the [Controllers documentation](../concepts/controllers.md) for more information.
 
 ## Models
 
@@ -61,7 +61,7 @@ module.exports = {
 
 Also, the table/collection name won't be `users` because you already have a `User` model. That's why, the framework will automatically prefix the table/collection name for this model with the name of the plugin. Which means in our example, the table/collection name of the `User` model of our plugin `Users & Permissions` will be `users-permissions_users`. If you want to force the table/collection name of the plugin's model, you can add the `collectionName` attribute in your model.
 
-Please refer to the [Models documentation](../guides/models.md) for more information.
+Please refer to the [Models documentation](../concepts/models.md) for more information.
 
 ## Policies
 
@@ -103,7 +103,7 @@ A plugin can have its own policies, such as adding security rules. For instance,
 }
 ```
 
-Please refer to the [Policies documentation](../guides/policies.md) for more information.
+Please refer to the [Policies documentation](../concepts/policies.md) for more information.
 
 ## ORM queries
 

docs/3.0.0-beta.x/plugin-development/frontend-development.md

@@ -4,7 +4,7 @@
 This feature is currently not available (coming soon).
 :::
 
-<!-- 
+<!--
 
 ## Admin panel
 
@@ -313,5 +313,5 @@ const Foo = props => (
 export default Foo;
 ```
 
-See [the documentation](https://github.com/yahoo/react-intl/wiki/Components#formattedmessage) for more extensive usage. 
+See [the documentation](https://github.com/yahoo/react-intl/wiki/Components#formattedmessage) for more extensive usage.
 -->

docs/3.0.0-beta.x/plugins/email.md

@@ -88,3 +88,26 @@ In the `send` function you will have access to:
 
 - `config` that contain configuration you setup in your admin panel
 - `options` that contain option your send when you called the `send` function from the email plugin service
+
+To use it you will have to publish it on **npm**.
+
+### Create a local provider
+
+If you want to create your own provider without publishing it on **npm** you can follow these steps:
+
+- Create a `providers` folder in your application.
+- Create your provider as explained in the documentation eg. `./providers/strapi-provider-email-[...]/...`
+- Then update your `package.json` to link your `strapi-provider-email-[...]` dependency to the [local path](https://docs.npmjs.com/files/package.json#local-paths) of your new provider.
+
+```json
+{
+  ...
+  "dependencies": {
+    ...
+    "strapi-provider-email-[...]": "file:providers/strapi-provider-email-[...]",
+    ...
+  }
+}
+```
+
+- Finally, run `yarn install` or `npm install` to install your new custom provider.

docs/3.0.0-beta.x/plugins/upload.md

@@ -293,3 +293,26 @@ Then, visit [http://localhost:1337/admin/plugins/upload/configurations/developme
 ## Create providers
 
 If you want to create your own, make sure the name starts with `strapi-provider-upload-` (duplicating an existing one will be easier to create), modify the `auth` config object and customize the `upload` and `delete` functions.
+
+To use it you will have to publish it on **npm**.
+
+### Create a local provider
+
+If you want to create your own provider without publishing it on **npm** you can follow these steps:
+
+- Create a `providers` folder in your application.
+- Create your provider as explained in the documentation eg. `./providers/strapi-provider-upload-[...]/...`
+- Then update your `package.json` to link your `strapi-provider-upload-[...]` dependency to the [local path](https://docs.npmjs.com/files/package.json#local-paths) of your new provider.
+
+```json
+{
+  ...
+  "dependencies": {
+    ...
+    "strapi-provider-upload-[...]": "file:providers/strapi-provider-upload-[...]",
+    ...
+  }
+}
+```
+
+- Finally, run `yarn install` or `npm install` to install your new custom provider.