From c6ba29da00a16ecc49f615752bb1490bab8ed9fb Mon Sep 17 00:00:00 2001 From: John Jago Date: Wed, 9 Jun 2021 13:23:16 -0500 Subject: [PATCH] docs: use descriptive links instead of "click here" (#25897) * 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 Co-authored-by: JJ Kasper --- contributing.md | 2 +- docs/advanced-features/amp-support/typescript.md | 2 +- docs/advanced-features/measuring-performance.md | 2 +- docs/api-reference/next.config.js/introduction.md | 4 ++-- docs/api-reference/next/amp.md | 2 +- docs/api-routes/introduction.md | 4 ++-- docs/authentication.md | 2 +- errors/postcss-ignored-plugin.md | 2 +- errors/postcss-shape.md | 2 +- examples/amp-first/README.md | 2 +- examples/i18n-routing/README.md | 2 +- examples/with-electron/README.md | 2 +- examples/with-netlify-cms/content/home.md | 2 +- examples/with-passport/README.md | 2 +- examples/with-rematch/README.md | 2 +- examples/with-stencil/packages/test-component/readme.md | 2 +- examples/with-unsplash/README.md | 2 +- examples/with-xstate/README.md | 2 +- 18 files changed, 20 insertions(+), 20 deletions(-) diff --git a/contributing.md b/contributing.md index 03d2a06cec1af..fa17d4ae5e2a7 100644 --- 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 index 273c943d94920..2f284c26d8035 100644 --- 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 index 329cddd452cf7..789d94bb8759c 100644 --- 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 index 474257638f4bc..097da42d032d1 100644 --- 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 index ac3ee8924b560..6cc212791168d 100644 --- 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 -> 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 index 4a97730b628f8..dab2047832ab3 100644 --- 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 index 8bb315622d329..4dd8981496a05 100644 --- 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 index 658ad57f28575..e8c73f1c69965 100644 --- 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 index 889fe55bcbc68..f121c889d04b1 100644 --- 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 index f1734f4feb8d8..4db9d29709f07 100644 --- 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 index f9956e869d054..be097c1aedd54 100644 --- 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 index 384df5a1d4907..fd95f3d8684e9 100644 --- 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 index 7e0dfd0c5737a..e559431f2b1c1 100644 --- 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 index 8c82af38da04f..4032d0f89f8f4 100644 --- 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 index dafa6cea2af18..e037ef1ea8948 100644 --- 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 index db8c4cca0c49f..d6812363edd4e 100644 --- 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 index 23535a5020cd6..452d880e72ddc 100644 --- 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 index 7c8ab9ffbe93e..d150c3d95f472 100644 --- 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