Add descriptions to documentation pages (#9901)

* Added descriptions * Added descriptions to API Reference * Added descriptions to API Routes * Added descriptions to basic features * Added descriptions to the routing docs * Update exportPathMap.md Co-authored-by: N Joe Haddad <timer150@gmail.com>

Add descriptions to documentation pages (#9901)
* Added descriptions * Added descriptions to API Reference * Added descriptions to API Routes * Added descriptions to basic features * Added descriptions to the routing docs * Update exportPathMap.md Co-authored-by: N Joe Haddad <timer150@gmail.com>
d1fdd2bb · Luis Alvarez D · Joe Haddad · 251f56b8 · d1fdd2bb · d1fdd2bb
52 changed file
--- a/docs/advanced-features/amp-support/adding-amp-components.md
+++ b/docs/advanced-features/amp-support/adding-amp-components.md
+---
+description: Add components from the AMP community to AMP pages, and make your pages more interactive.
+---
+
 # Adding AMP Components

 The AMP community provide [many components](https://amp.dev/documentation/components/) to make AMP pages more interactive. You can add these components to your page by using `next/head`, as in the following example:

--- a/docs/advanced-features/amp-support/amp-in-static-html-export.md
+++ b/docs/advanced-features/amp-support/amp-in-static-html-export.md
+---
+description: Learn how AMP pages are created when used together with `next export`.
+---
+
 # AMP in Static HTML export

 When using `next export` to do [Static HTML export](/docs/advanced-features/static-html-export.md) statically prerender pages, Next.js will detect if the page supports AMP and change the exporting behavior based on that.

--- a/docs/advanced-features/amp-support/amp-validation.md
+++ b/docs/advanced-features/amp-support/amp-validation.md
+---
+description: AMP pages are automatically validated by Next.js during development and on build. Learn more about it here.
+---
+
 # AMP Validation

 AMP pages are automatically validated with [amphtml-validator](https://www.npmjs.com/package/amphtml-validator) during development. Errors and warnings will appear in the terminal where you started Next.js.

--- a/docs/advanced-features/amp-support/introduction.md
+++ b/docs/advanced-features/amp-support/introduction.md
+---
+description: With minimal config, and without leaving React, you can start adding AMP and improve the performance and speed of your pages.
+---
+
 # AMP Support

 <details>

--- a/docs/advanced-features/amp-support/typescript.md
+++ b/docs/advanced-features/amp-support/typescript.md
+---
+description: Using AMP with TypeScript? Extend your typings to allow AMP components.
+---
+
 # TypeScript

 AMP currently doesn't have built-in types for TypeScript, but it's in their roadmap ([#13791](https://github.com/ampproject/amphtml/issues/13791)).

--- a/docs/advanced-features/automatic-static-optimization.md
+++ b/docs/advanced-features/automatic-static-optimization.md
+---
+description: Next.js automatically optimizes your app to be static HTML whenever possible. Learn how it works here.
+---
+
 # Automatic Static Optimization

 Next.js automatically determines that a page is static (can be prerendered) if it has no blocking data requirements. This determination is made by the absence of `getInitialProps` in the page.

--- a/docs/advanced-features/custom-app.md
+++ b/docs/advanced-features/custom-app.md
+---
+description: Control page initialization and add a layout that persists for all pages by overriding the default App component used by Next.js.
+---
+
 # Custom `App`

 Next.js uses the `App` component to initialize pages. You can override it and control the page initialization. Which allows you to do amazing things like:

--- a/docs/advanced-features/custom-document.md
+++ b/docs/advanced-features/custom-document.md
+---
+description: Extend the default document markup added by Next.js.
+---
+
 # Custom `Document`

 A custom `Document` is commonly used to augment your application's `<html>` and `<body>` tags. This is necessary because Next.js pages skip the definition of the surrounding document's markup.

--- a/docs/advanced-features/custom-error-page.md
+++ b/docs/advanced-features/custom-error-page.md
+---
+description: Override and extend the built-in Error page to handle custom errors.
+---
+
 # Custom Error Page

 **404** or **500** errors are handled both client-side and server-side by the `Error` component. If you wish to override it, define the file `pages/_error.js` and add the following code:

--- a/docs/advanced-features/custom-server.md
+++ b/docs/advanced-features/custom-server.md
+---
+description: Start a Next.js app programmatically using a custom server.
+---
+
 # Custom Server

 <details>

--- a/docs/advanced-features/customizing-babel-config.md
+++ b/docs/advanced-features/customizing-babel-config.md
+---
+description: Extend the babel preset added by Next.js with your own configs.
+---
+
 # Customizing Babel Config

 <details>

--- a/docs/advanced-features/dynamic-import.md
+++ b/docs/advanced-features/dynamic-import.md
+---
+description: Dynamically import JavaScript modules and React Components and split your code into manageable chunks.
+---
+
 # Dynamic Import

 <details>

--- a/docs/advanced-features/src-directory.md
+++ b/docs/advanced-features/src-directory.md
+---
+description: Save pages under the `src` directory as an alternative to the root `pages` directory.
+---
+
 # `src` Directory

 Pages can also be added under `src/pages` as an alternative to the root `pages` directory.

--- a/docs/advanced-features/static-html-export.md
+++ b/docs/advanced-features/static-html-export.md
+---
+description: Export your Next.js app to static HTML, and run it standalone without the need of a Node.js server.
+---
+
 # Static HTML Export

 <details>

--- a/docs/api-reference/cli.md
+++ b/docs/api-reference/cli.md
+---
+description: The Next.js CLI allows you to start, build, and export your application. Learn more about it here.
+---
+
 # Next.js CLI

 The Next.js CLI allows you to start, build, and export your application.

--- a/docs/api-reference/data-fetching/getInitialProps.md
+++ b/docs/api-reference/data-fetching/getInitialProps.md
+---
+description: Enable Server-Side Rendering in a page and do initial data population with `getInitialProps`.
+---
+
 # getInitialProps

 <details>

--- a/docs/api-reference/next.config.js/build-target.md
+++ b/docs/api-reference/next.config.js/build-target.md
+---
+description: Learn more about the build targets used by Next.js, which decide the way your application is built and run.
+---
+
 # Build Target

 Next.js supports various build targets, each changing the way your application is built and run. We'll explain each of the targets below.

--- a/docs/api-reference/next.config.js/cdn-support-with-asset-prefix.md
+++ b/docs/api-reference/next.config.js/cdn-support-with-asset-prefix.md
+---
+description: A custom asset prefix allows you serve static assets from a CDN. Learn more about it here.
+---
+
 # CDN Support with Asset Prefix

 To set up a [CDN](https://en.wikipedia.org/wiki/Content_delivery_network), you can set up an asset prefix and configure your CDN's origin to resolve to the domain that Next.js is hosted on.

--- a/docs/api-reference/next.config.js/compression.md
+++ b/docs/api-reference/next.config.js/compression.md
+---
+description: Next.js provides gzip compression to compress rendered content and static files, it only works with the server target. Learn more about it here.
+---
+
 # Compression

 Next.js provides [**gzip**](https://tools.ietf.org/html/rfc6713#section-3) compression to compress rendered content and static files. Compression only works with the [`server` target](/docs/api-reference/next.config.js/build-target.md#server-target). In general you will want to enable compression on a HTTP proxy like [nginx](https://www.nginx.com/), to offload load from the `Node.js` process.

--- a/docs/api-reference/next.config.js/configuring-onDemandEntries.md
+++ b/docs/api-reference/next.config.js/configuring-onDemandEntries.md
+---
+description: Configure how Next.js will dispose and keep in memory pages created in development.
+---
+
 # Configuring onDemandEntries

 Next.js exposes some options that give you some control over how the server will dispose or keep in memory built pages in development.

--- a/docs/api-reference/next.config.js/configuring-the-build-id.md
+++ b/docs/api-reference/next.config.js/configuring-the-build-id.md
+---
+description: Configure the build id, which is used to identify the current build in which your application is being served.
+---
+
 # Configuring the Build ID

 Next.js uses a constant id generated at build time to identify which version of your application is being served. This can cause problems in multi-server deployments when `next build` is ran on every server. In order to keep a static build id between builds you can provide your own build id.

--- a/docs/api-reference/next.config.js/custom-page-extensions.md
+++ b/docs/api-reference/next.config.js/custom-page-extensions.md
+---
+description: Extend the default page extensions used by Next.js when resolving pages in the pages directory.
+---
+
 # Custom Page Extensions

 Aimed at modules like [@next/mdx](https://github.com/zeit/next.js/tree/canary/packages/next-mdx), which adds support for pages ending with `.mdx`. You can configure the extensions looked for in the `pages` directory when resolving pages.

--- a/docs/api-reference/next.config.js/custom-webpack-config.md
+++ b/docs/api-reference/next.config.js/custom-webpack-config.md
+---
+description: Extend the default webpack config added by Next.js.
+---
+
 # Custom Webpack Config

 Some commonly asked for features are available as plugins:

--- a/docs/api-reference/next.config.js/disabling-etag-generation.md
+++ b/docs/api-reference/next.config.js/disabling-etag-generation.md
+---
+description: Next.js will generate etags for every page by default. Learn more about how to disable etag generation here.
+---
+
 # Disabling ETag Generation

 Next.js will generate [etags](https://en.wikipedia.org/wiki/HTTP_ETag) for every page by default. You may want to disable etag generation for HTML pages depending on your cache strategy.

--- a/docs/api-reference/next.config.js/disabling-x-powered-by.md
+++ b/docs/api-reference/next.config.js/disabling-x-powered-by.md
+---
+description: Next.js will add `x-powered-by` to the request headers by default. Learn to opt-out of it here.
+---
+
 # Disabling x-powered-by

 By default Next.js will add `x-powered-by` to the request headers. To opt-out of it, open `next.config.js` and disable the `poweredByHeader` config:

--- a/docs/api-reference/next.config.js/environment-variables.md
+++ b/docs/api-reference/next.config.js/environment-variables.md
+---
+description: Learn to add and access environment variables in your Next.js application at build time.
+---
+
 # Environment Variables

 <details>

--- a/docs/api-reference/next.config.js/exportPathMap.md
+++ b/docs/api-reference/next.config.js/exportPathMap.md
+---
+description: Customize the pages that will be exported as HTML files when using `next export`.
+---
+
 # exportPathMap

 > This feature is exclusive of `next export`. Please refer to [Static HTML export](/docs/advanced-features/static-html-export.md) if you want to learn more about it.

--- a/docs/api-reference/next.config.js/ignoring-typescript-errors.md
+++ b/docs/api-reference/next.config.js/ignoring-typescript-errors.md
+---
+description: Next.js reports TypeScript errors by default. Learn to opt-out of this behavior here.
+---
+
 # Ignoring TypeScript Errors

 Next.js reports TypeScript errors by default. If you don't want to leverage this behavior and prefer something else instead, like your editor's integration, you may want to disable it.

--- a/docs/api-reference/next.config.js/introduction.md
+++ b/docs/api-reference/next.config.js/introduction.md
+---
+description: learn more about the configuration file used by Next.js to handle your application.
+---
+
 # next.config.js

 For custom advanced behavior of Next.js, you can create a `next.config.js` in the root of your project directory (next to `package.json`).

--- a/docs/api-reference/next.config.js/runtime-configuration.md
+++ b/docs/api-reference/next.config.js/runtime-configuration.md
+---
+description: Add client and server runtime configuration to your Next.js app.
+---
+
 # Runtime Configuration

 > Generally you'll want to use [build-time environment variables](/docs/api-reference/next.config.js/environment-variables.md) to provide your configuration. The reason for this is that runtime configuration adds rendering / initialization overhead and is incompatible with [Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md).

--- a/docs/api-reference/next.config.js/setting-a-custom-build-directory.md
+++ b/docs/api-reference/next.config.js/setting-a-custom-build-directory.md
+---
+description: Set a custom build directory to use instead of the default .next directory.
+---
+
 # Setting a custom build directory

 You can specify a name to use for a custom build directory to use instead of `.next`.

--- a/docs/api-reference/next.config.js/static-optimization-indicator.md
+++ b/docs/api-reference/next.config.js/static-optimization-indicator.md
+---
+description: Optimized pages include an indicator to let you know if it's being statically optimized. You can opt-out of it here.
+---
+
 # Static Optimization Indicator

 When a page qualifies for [Automatic Static Optimization](/docs/advanced-features/automatic-static-optimization.md) we show an indicator to let you know.

--- a/docs/api-reference/next/amp.md
+++ b/docs/api-reference/next/amp.md
+---
+description: Enable AMP in a page, and control the way Next.js adds AMP to the page with the AMP config.
+---
+
 # next/amp

 <details>

--- a/docs/api-reference/next/head.md
+++ b/docs/api-reference/next/head.md
+---
+description: Add custom elements to the `head` of your page with the built-in Head component.
+---
+
 # next/head

 <details>

--- a/docs/api-reference/next/link.md
+++ b/docs/api-reference/next/link.md
+---
+description: Enable client-side transitions between routes with the built-in Link component.
+---
+
 # next/link

 <details>

--- a/docs/api-reference/next/router.md
+++ b/docs/api-reference/next/router.md
+---
+description: Learn more about the API of the Next.js Router, and access the router instance in your page with the useRouter hook.
+---
+
 # next/router

 > Before moving forward, we recommend you to read [Routing Introduction](/docs/routing/introduction.md) first.

--- a/docs/api-routes/api-middlewares.md
+++ b/docs/api-routes/api-middlewares.md
+---
+description: API Routes provide built-in middlewares that parse the incoming request. Learn more about them here.
+---
+
 # API Middlewares

 API routes provide built in middlewares which parse the incoming request (`req`). Those middlewares are:

--- a/docs/api-routes/dynamic-api-routes.md
+++ b/docs/api-routes/dynamic-api-routes.md
+---
+description: You can add the dynamic routes used for pages to API Routes too. Learn how it works here.
+---
+
 # Dynamic API Routes

-API pages support [dynamic routes](/docs/routing/dynamic-routes.md), and follow the same file naming rules used for `pages`.
+API routes support [dynamic routes](/docs/routing/dynamic-routes.md), and follow the same file naming rules used for `pages`.

 For example, the API route `pages/api/post/[pid].js` has the following code:


--- a/docs/api-routes/introduction.md
+++ b/docs/api-routes/introduction.md
+---
+description: Next.js supports API Routes, which allow you to build your API without leaving your Next.js app. Learn how it works here.
+---
+
 # API Routes

 <details>

--- a/docs/api-routes/response-helpers.md
+++ b/docs/api-routes/response-helpers.md
+---
+description: API Routes include a set of Express.js-like methods for the response to help you creating new API endpoints. Learn how it works here.
+---
+
 # Response Helpers

 The response (`res`) includes a set of Express.js-like methods to improve the developer experience and increase the speed of creating new API endpoints, take a look at the following example:

--- a/docs/basic-features/built-in-css-support.md
+++ b/docs/basic-features/built-in-css-support.md
+---
+description: Next.js includes styled-jsx by default for isolated and scoped CSS support, but you can also use any other CSS-in-JS solution!. Learn more here.
+---
+
 # Built-in CSS Support

 <details>

--- a/docs/basic-features/data-fetching.md
+++ b/docs/basic-features/data-fetching.md
+---
+description: Next.js can handle data fetching in multiple ways for server-rendered and static pages. Learn how it works here.
+---
+
 # Data fetching

 Next.js has 2 pre-rendering modes built-in:

--- a/docs/basic-features/pages.md
+++ b/docs/basic-features/pages.md
+---
+description: Next.js pages are React Components exported in a file in the pages directory. Learn how they work here.
+---
+
 # Pages

 A page is a [React Component](https://reactjs.org/docs/components-and-props.html) exported from a `.js`, `.ts`, or `.tsx` file in the `pages` directory.

--- a/docs/basic-features/static-file-serving.md
+++ b/docs/basic-features/static-file-serving.md
+---
+description: Next.js allows you to serve static files, like images, in the public directory. You can learn how it works here.
+---
+
 # Static File Serving

 Next.js can serve static files, like images, under a folder called `public` in the root directory. Files inside `public` can then be referenced by your code starting from the base URL (`/`).

--- a/docs/basic-features/typescript.md
+++ b/docs/basic-features/typescript.md
+---
+description: Next.js supports TypeScript by default and has built-in types for pages and the API. You can get started with Next.js and TypeScript here.
+---
+
 # TypeScript

 <details>

--- a/docs/deployment.md
+++ b/docs/deployment.md
+---
+description: Compile and deploy your Next.js app to production with ZEIT Now and other hosting alternatives.
+---
+
 # Deployment

 To go to production Next.js has a `next build` command. When ran it will compile your project and automatically apply numerous optimizations.

--- a/docs/faq.md
+++ b/docs/faq.md
+---
+description: Get to know more about Next.js with the frequently asked questions.
+---
+
 # Frequently Asked Questions

 <details>

--- a/docs/getting-started.md
+++ b/docs/getting-started.md
 ---
-description: Getting started with Next.js.
+description: Get started with Next.js in the official documentation, and learn more about all our features!
 ---

 # Getting Started

--- a/docs/routing/dynamic-routes.md
+++ b/docs/routing/dynamic-routes.md
+---
+description: Dynamic Routes are pages that allow you to add custom params to your URLs. Start creating Dynamic Routes and learn more here.
+---
+
 # Dynamic Routes

 <details>

--- a/docs/routing/imperatively.md
+++ b/docs/routing/imperatively.md
+---
+description: Client-side navigations are also possible using the Router API instead of the Link component. Learn more here.
+---
+
 # Imperatively

 <details>

--- a/docs/routing/introduction.md
+++ b/docs/routing/introduction.md
+---
+description: Next.js has a built-in, opinionated, and file-system based Router. You can learn how it works here.
+---
+
 # Routing

 Next.js has a file-system based router built on the [concept of pages](/docs/basic-features/pages.md).

--- a/docs/routing/shallow-routing.md
+++ b/docs/routing/shallow-routing.md
+---
+description: You can use shallow routing to change the URL without triggering a new page change. Learn more here.
+---
+
 # Shallow Routing

 <details>