docs: use descriptive links instead of "click here" (vercel#25897)

johnjago · leerob · ijjk · web-flow · commit c6ba29da00a1 · 2021-06-09T13:23:16.000-05:00
* docs: use descriptive links instead of "click here"

Linking text such as "here" or "click here" is not accessible (and
doesn't look that great either). The best example of why it's better to
use link text that provides context is that some screen readers allow
navigation by links alone. If all links say "click here", then how does
the user know which one to go to?

I tried to make the minimal change necessary to make the link text
descriptive but had to reword a few sentences that didn't read well.

* Apply suggestions from code review

Co-authored-by: Lee Robinson &lt;me@leerob.io&gt;
Co-authored-by: JJ Kasper &lt;jj@jjsweb.site&gt;
diff --git a/contributing.md b/contributing.md
@@ -1,6 +1,6 @@
 # Contributing to Next.js
 
-Our Commitment to Open Source can be found [here](https://vercel.com/oss).
+Read about our [Commitment to Open Source](https://vercel.com/oss).
 
 1. [Fork](https://help.github.com/articles/fork-a-repo/) this repository to your own GitHub account and then [clone](https://help.github.com/articles/cloning-a-repository/) it to your local device.
 2. Create a new branch: `git checkout -b MY_BRANCH_NAME`
diff --git a/docs/advanced-features/amp-support/typescript.md b/docs/advanced-features/amp-support/typescript.md
@@ -6,4 +6,4 @@ description: Using AMP with TypeScript? Extend your typings to allow AMP compone
 
 AMP currently doesn't have built-in types for TypeScript, but it's in their roadmap ([#13791](https://github.com/ampproject/amphtml/issues/13791)).
 
-As a workaround you can manually create a file called `amp.d.ts` inside your project and add the custom types described [here](https://stackoverflow.com/a/50601125).
+As a workaround you can manually create a file called `amp.d.ts` inside your project and add these [custom types](https://stackoverflow.com/a/50601125).
diff --git a/docs/advanced-features/measuring-performance.md b/docs/advanced-features/measuring-performance.md
@@ -175,7 +175,7 @@ export function reportWebVitals(metric) {
 > }
 > ```
 >
-> Read more about sending results to Google Analytics [here](https://github.com/GoogleChrome/web-vitals#send-the-results-to-google-analytics).
+> Read more about [sending results to Google Analytics](https://github.com/GoogleChrome/web-vitals#send-the-results-to-google-analytics).
 
 ## TypeScript
 
diff --git a/docs/api-reference/next.config.js/introduction.md b/docs/api-reference/next.config.js/introduction.md
@@ -26,7 +26,7 @@ module.exports = (phase, { defaultConfig }) => {
 }
 ```
 
-`phase` is the current context in which the configuration is loaded. You can see the available phases [here](https://github.com/vercel/next.js/blob/canary/packages/next/next-server/lib/constants.ts#L1-L4). Phases can be imported from `next/constants`:
+`phase` is the current context in which the configuration is loaded. You can see the [available phases](https://github.com/vercel/next.js/blob/canary/packages/next/next-server/lib/constants.ts#L1-L4). Phases can be imported from `next/constants`:
 
 ```js
 const { PHASE_DEVELOPMENT_SERVER } = require('next/constants')
@@ -44,7 +44,7 @@ module.exports = (phase, { defaultConfig }) => {
 }
 ```
 
-The commented lines are the place where you can put the configs allowed by `next.config.js`, which are defined [here](https://github.com/vercel/next.js/blob/canary/packages/next/next-server/server/config-shared.ts#L68).
+The commented lines are the place where you can put the configs allowed by `next.config.js`, which are [defined in this file](https://github.com/vercel/next.js/blob/canary/packages/next/next-server/server/config-shared.ts#L68).
 
 However, none of the configs are required, and it's not necessary to understand what each config does. Instead, search for the features you need to enable or modify in this section and they will show you what to do.
 
diff --git a/docs/api-reference/next/amp.md b/docs/api-reference/next/amp.md
@@ -11,7 +11,7 @@ description: Enable AMP in a page, and control the way Next.js adds AMP to the p
   </ul>
 </details>
 
-> AMP support is one of our advanced features, you can read more about it [here](/docs/advanced-features/amp-support/introduction.md).
+> AMP support is one of our advanced features, you can [read more about AMP here](/docs/advanced-features/amp-support/introduction.md).
 
 To enable AMP, add the following config to your page:
 
diff --git a/docs/api-routes/introduction.md b/docs/api-routes/introduction.md
@@ -29,8 +29,8 @@ export default function handler(req, res) {
 
 For an API route to work, you need to export a function as default (a.k.a **request handler**), which then receives the following parameters:
 
-- `req`: An instance of [http.IncomingMessage](https://nodejs.org/api/http.html#http_class_http_incomingmessage), plus some pre-built middlewares you can see [here](/docs/api-routes/api-middlewares.md)
-- `res`: An instance of [http.ServerResponse](https://nodejs.org/api/http.html#http_class_http_serverresponse), plus some helper functions you can see [here](/docs/api-routes/response-helpers.md)
+- `req`: An instance of [http.IncomingMessage](https://nodejs.org/api/http.html#http_class_http_incomingmessage), plus some [pre-built middlewares](/docs/api-routes/api-middlewares.md)
+- `res`: An instance of [http.ServerResponse](https://nodejs.org/api/http.html#http_class_http_serverresponse), plus some [helper functions](/docs/api-routes/response-helpers.md)
 
 To handle different HTTP methods in an API route, you can use `req.method` in your request handler, like so:
 
diff --git a/docs/authentication.md b/docs/authentication.md
@@ -48,7 +48,7 @@ const Profile = () => {
 export default Profile
 ```
 
-You can view this example in action [here](https://next-with-iron-session.vercel.app/). Check out the [`with-iron-session`](https://github.com/vercel/next.js/tree/canary/examples/with-iron-session) example to see how it works.
+You can view this [example in action](https://next-with-iron-session.vercel.app/). Check out the [`with-iron-session`](https://github.com/vercel/next.js/tree/canary/examples/with-iron-session) example to see how it works.
 
 ### Authenticating Server-Rendered Pages
 
diff --git a/errors/postcss-ignored-plugin.md b/errors/postcss-ignored-plugin.md
@@ -17,4 +17,4 @@ Remove the plugin specified in the error message from your custom PostCSS config
 #### How do I configure CSS Modules?
 
 CSS Modules are supported in [Next.js' built-in CSS support](https://nextjs.org/docs/advanced-features/customizing-postcss-config).
-You can [read more](https://nextjs.org/docs/advanced-features/customizing-postcss-config) about how to use them [here](https://nextjs.org/docs/advanced-features/customizing-postcss-config).
+You can [read more about how to use CSS Modules here](https://nextjs.org/docs/advanced-features/customizing-postcss-config).
diff --git a/errors/postcss-shape.md b/errors/postcss-shape.md
@@ -39,7 +39,7 @@ module.exports = {
 }
 ```
 
-You can [read more](https://nextjs.org/docs/advanced-features/customizing-postcss-config) about configuring PostCSS in Next.js [here](https://nextjs.org/docs/advanced-features/customizing-postcss-config).
+You can [read more about configuring PostCSS in Next.js here](https://nextjs.org/docs/advanced-features/customizing-postcss-config).
 
 #### Common Errors
 
diff --git a/examples/amp-first/README.md b/examples/amp-first/README.md
@@ -1,6 +1,6 @@
 # AMP First Boilerplate ⚡
 
-This example sets up the boilerplate for an AMP First Site. You can see a live version [here](https://my-next-app.sebastianbenz.vercel.app). The boilerplate includes the following features:
+This example sets up the boilerplate for an AMP First Site. You can see a [live version here](https://my-next-app.sebastianbenz.vercel.app). The boilerplate includes the following features:
 
 - AMP Extension helpers (`amp-state`, `amp-script`, ...)
 - AMP Serviceworker integration
diff --git a/examples/i18n-routing/README.md b/examples/i18n-routing/README.md
@@ -2,7 +2,7 @@
 
 This example shows how to create internationalized pages using Next.js and the i18n routing feature. It shows a normal page, a non-dynamic `getStaticProps` page, a dynamic `getStaticProps` page, and a `getServerSideProps` page.
 
-For further documentation on this feature see the documentation [here](https://nextjs.org/docs/advanced-features/i18n-routing)
+For further documentation on this feature see the [Internationalized Routing docs](https://nextjs.org/docs/advanced-features/i18n-routing).
 
 ## Preview
 
diff --git a/examples/with-electron/README.md b/examples/with-electron/README.md
@@ -4,7 +4,7 @@ This example shows how you can use Next.js inside an Electron application to avo
 
 For development it's going to run an HTTP server and let Next.js handle routing. In production it uses `next export` to pre-generate HTML static files and uses them in your app instead of running an HTTP server.
 
-**You can find a detailed documentation about how to build Electron apps with Next.js [here](https://leo.im/2017/electron-next)!**
+**For detailed documentation about how to build Electron apps with Next.js, see [this blog post](https://leo.im/2017/electron-next)!**
 
 ## How to use
 
diff --git a/examples/with-netlify-cms/content/home.md b/examples/with-netlify-cms/content/home.md
@@ -5,4 +5,4 @@ date: 2019-03-17T19:31:20.591Z
 
 ## Welcome to the Home Page
 
-If you want to know more about Next.js + Netlifycms go to the official tutorial [here](https://www.netlifycms.org/docs/nextjs/).
+If you want to know more about Next.js + Netlify CMS go to their [official tutorial](https://www.netlifycms.org/docs/nextjs/).
diff --git a/examples/with-passport/README.md b/examples/with-passport/README.md
@@ -4,7 +4,7 @@ This example show how to use [Passport.js](http://www.passportjs.org) with Next.
 
 The example shows how to do a login, signup and logout; and to get the user info using a hook with [SWR](https://swr.vercel.app).
 
-A DB is not included. You can use any db you want and add it [here](lib/user.js).
+A database is not included. You can use any database you want and add it [in this file](lib/user.js).
 
 The login cookie is httpOnly, meaning it can only be accessed by the API, and it's encrypted using [@hapi/iron](https://hapi.dev/family/iron) for more security.
 
diff --git a/examples/with-rematch/README.md b/examples/with-rematch/README.md
@@ -2,7 +2,7 @@
 
 This example has two pages. The first page has a counter which can be incremented synchronously or asynchronously. The second page is a page which shows a list of github users. It fetches data from the github api using this [endpoint](api.github.com/users).
 
-Since rematch is utility which uses redux under the hood, some elements like `store.js` and `withRematch` are very similar to the `with-redux` example. Please go through the `with-redux` example [here](https://github.com/vercel/next.js/tree/master/examples/with-redux) before reading further if you are not familiar with how redux is integrated with nextjs. Rematch is just an extension for Redux so a lot of elements are the same.
+Since rematch is utility which uses redux under the hood, some elements like `store.js` and `withRematch` are very similar to the `with-redux` example. Please go through the [`with-redux` example](https://github.com/vercel/next.js/tree/master/examples/with-redux) before reading further if you are not familiar with how redux is integrated with Next.js. Rematch is just an extension for Redux so a lot of elements are the same.
 
 ## Preview
 
diff --git a/examples/with-stencil/packages/test-component/readme.md b/examples/with-stencil/packages/test-component/readme.md
@@ -43,7 +43,7 @@ To run the unit tests for the components, run:
 npm test
 ```
 
-Need help? Check out our docs [here](https://stenciljs.com/docs/my-first-component).
+Need help? [Check out our docs](https://stenciljs.com/docs/my-first-component).
 
 ## Naming Components
 
diff --git a/examples/with-unsplash/README.md b/examples/with-unsplash/README.md
@@ -24,7 +24,7 @@ First, you'll need to [create an account on Unsplash](https://unsplash.com/) if
 
 ### Step 1. Create an app on Unsplash
 
-To create a new application on Unsplash, click [here](https://unsplash.com/oauth/applications/new) or go to https://unsplash.com/oauth/applications/new.
+Create a [new application on Unsplash](https://unsplash.com/oauth/applications/new).
 
 Before creating an app you'll have to accept the terms for API use:
 
diff --git a/examples/with-xstate/README.md b/examples/with-xstate/README.md
@@ -1,6 +1,6 @@
 # XState example
 
-This example shows how to integrate XState in Next.js. For more info about XState you can visit [here](https://xstate.js.org/).
+This example shows how to integrate XState in Next.js. [Learn more about XState](https://xstate.js.org/).
 
 ## Preview
 

Original file line number	Diff line number	Diff line change
`@@ -6,4 +6,4 @@ description: Using AMP with TypeScript? Extend your typings to allow AMP compone`
`6`	`6`
`7`	`7`	`AMP currently doesn't have built-in types for TypeScript, but it's in their roadmap ([#13791](https://github.com/ampproject/amphtml/issues/13791)).`
`8`	`8`
`9`		-As a workaround you can manually create a file called `amp.d.ts` inside your project and add the custom types described [here](https://stackoverflow.com/a/50601125).
	`9`	+As a workaround you can manually create a file called `amp.d.ts` inside your project and add these [custom types](https://stackoverflow.com/a/50601125).
Original file line number	Diff line number	Diff line change
`@@ -175,7 +175,7 @@ export function reportWebVitals(metric) {`
`175`	`175`	`> }`
`176`	`176`	> ```
`177`	`177`	`>`
`178`		`-> Read more about sending results to Google Analytics [here](https://github.com/GoogleChrome/web-vitals#send-the-results-to-google-analytics).`
	`178`	`+> Read more about [sending results to Google Analytics](https://github.com/GoogleChrome/web-vitals#send-the-results-to-google-analytics).`
`179`	`179`
`180`	`180`	`## TypeScript`
`181`	`181`
Original file line number	Diff line number	Diff line change
`@@ -26,7 +26,7 @@ module.exports = (phase, { defaultConfig }) => {`
`26`	`26`	`}`
`27`	`27`	```
`28`	`28`
`29`		-`phase` is the current context in which the configuration is loaded. You can see the available phases [here](https://github.com/vercel/next.js/blob/canary/packages/next/next-server/lib/constants.ts#L1-L4). Phases can be imported from `next/constants`:
	`29`	+`phase` is the current context in which the configuration is loaded. You can see the [available phases](https://github.com/vercel/next.js/blob/canary/packages/next/next-server/lib/constants.ts#L1-L4). Phases can be imported from `next/constants`:
`30`	`30`
`31`	`31`	```js
`32`	`32`	`const { PHASE_DEVELOPMENT_SERVER } = require('next/constants')`
`@@ -44,7 +44,7 @@ module.exports = (phase, { defaultConfig }) => {`
`44`	`44`	`}`
`45`	`45`	```
`46`	`46`
`47`		-The commented lines are the place where you can put the configs allowed by `next.config.js`, which are defined [here](https://github.com/vercel/next.js/blob/canary/packages/next/next-server/server/config-shared.ts#L68).
	`47`	+The commented lines are the place where you can put the configs allowed by `next.config.js`, which are [defined in this file](https://github.com/vercel/next.js/blob/canary/packages/next/next-server/server/config-shared.ts#L68).
`48`	`48`
`49`	`49`	`However, none of the configs are required, and it's not necessary to understand what each config does. Instead, search for the features you need to enable or modify in this section and they will show you what to do.`
`50`	`50`
Original file line number	Diff line number	Diff line change
`@@ -39,7 +39,7 @@ module.exports = {`
`39`	`39`	`}`
`40`	`40`	```
`41`	`41`
`42`		`-You can [read more](https://nextjs.org/docs/advanced-features/customizing-postcss-config) about configuring PostCSS in Next.js [here](https://nextjs.org/docs/advanced-features/customizing-postcss-config).`
	`42`	`+You can [read more about configuring PostCSS in Next.js here](https://nextjs.org/docs/advanced-features/customizing-postcss-config).`
`43`	`43`
`44`	`44`	`#### Common Errors`
`45`	`45`