Improve Link documentation

[chibicode]

This PR improves the next/link API documentation in general.

First, I grouped two sections about forwardRef and passHref next to each other because they both talk about gotchas when using custom chidlren. This made passHref to appear earlier in the page, which I think is good because a lot of people seem to run into this issue.

Second, I explicitly used styled-components as an example for passHref. Previously it was using Unexpected_A, which was a very strange name (what’s unexpected?). styled-components is popular enough (see this comment which got a lot of upvotes), and even if the user's using some other libraries, they'll probably understand the styled-components example better than Unexpected_A.

Third, I tightened the wording for passHref doc. The earlier version (from #2503) was too wordy.

Fourth, I added a note about emotion - if you use emotion, even if you use the <a> tag directly, you’ll still need passHref because emotion’s custom JSX pragma strips away the type attribute from each element. Emotion is pretty popular, and you basically would have to find this issue to figure out why this is happening, so I thought adding a note here would help.

Fifth, the forwardRef example (from #8428) was missing passHref on MyButton.

[ijjk]

Stats from current PR

Default Server Mode

General

	zeit/next.js canary	chibicode/next.js improve-link-documentation	Change
buildDuration	13.3s	12.5s	-813ms
nodeModulesSize	51 MB	51 MB	✓

Client Bundles (main, webpack, commons)

	zeit/next.js canary	chibicode/next.js improve-link-documentation	Change
main-HASH.js gzip	5.1 kB	5.1 kB	✓
webpack-HASH.js gzip	746 B	746 B	✓
4952ddcd88e7..54d3.js gzip	4.68 kB	4.68 kB	✓
commons.HASH.js gzip	4.06 kB	4.06 kB	✓
de003c3a9d30..d57b.js gzip	16.1 kB	16.1 kB	✓
framework.HASH.js gzip	39.1 kB	39.1 kB	✓
Overall change	69.8 kB	69.8 kB	✓

Client Bundles (main, webpack, commons) Modern

	zeit/next.js canary	chibicode/next.js improve-link-documentation	Change
main-HASH.module.js gzip	4.1 kB	4.1 kB	✓
webpack-HASH..dule.js gzip	746 B	746 B	✓
4952ddcd88e7..dule.js gzip	5.56 kB	5.56 kB	✓
de003c3a9d30..dule.js gzip	15 kB	15 kB	✓
framework.HA..dule.js gzip	39.1 kB	39.1 kB	✓
Overall change	64.5 kB	64.5 kB	✓

Legacy Client Bundles (polyfills)

	zeit/next.js canary	chibicode/next.js improve-link-documentation	Change
polyfills-HASH.js gzip	4.76 kB	4.76 kB	✓
Overall change	4.76 kB	4.76 kB	✓

Client Pages

	zeit/next.js canary	chibicode/next.js improve-link-documentation	Change
_app.js gzip	1.15 kB	1.15 kB	✓
_error.js gzip	4.07 kB	4.07 kB	✓
hooks.js gzip	779 B	779 B	✓
index.js gzip	222 B	222 B	✓
link.js gzip	2.89 kB	2.89 kB	✓
routerDirect.js gzip	283 B	283 B	✓
withRouter.js gzip	282 B	282 B	✓
Overall change	9.68 kB	9.68 kB	✓

Client Pages Modern

	zeit/next.js canary	chibicode/next.js improve-link-documentation	Change
_app.module.js gzip	576 B	576 B	✓
_error.module.js gzip	3.06 kB	3.06 kB	✓
hooks.module.js gzip	371 B	371 B	✓
index.module.js gzip	212 B	212 B	✓
link.module.js gzip	2.46 kB	2.46 kB	✓
routerDirect..dule.js gzip	273 B	273 B	✓
withRouter.m..dule.js gzip	272 B	272 B	✓
Overall change	7.22 kB	7.22 kB	✓

Client Build Manifests

	zeit/next.js canary	chibicode/next.js improve-link-documentation	Change
_buildManifest.js gzip	61 B	61 B	✓
_buildManife..dule.js gzip	61 B	61 B	✓
Overall change	122 B	122 B	✓

Rendered Page Sizes

	zeit/next.js canary	chibicode/next.js improve-link-documentation	Change
index.html gzip	1.02 kB	1.02 kB	✓
link.html gzip	1.03 kB	1.03 kB	✓
withRouter.html gzip	1.02 kB	1.02 kB	✓
Overall change	3.07 kB	3.07 kB	✓

---

Serverless Mode

General

	zeit/next.js canary	chibicode/next.js improve-link-documentation	Change
buildDuration	13.4s	14.2s	⚠️ +881ms
nodeModulesSize	51 MB	51 MB	✓

Client Bundles (main, webpack, commons)

	zeit/next.js canary	chibicode/next.js improve-link-documentation	Change
main-HASH.js gzip	5.1 kB	5.1 kB	✓
webpack-HASH.js gzip	746 B	746 B	✓
4952ddcd88e7..54d3.js gzip	4.68 kB	4.68 kB	✓
commons.HASH.js gzip	4.06 kB	4.06 kB	✓
de003c3a9d30..d57b.js gzip	16.1 kB	16.1 kB	✓
framework.HASH.js gzip	39.1 kB	39.1 kB	✓
Overall change	69.8 kB	69.8 kB	✓

Client Bundles (main, webpack, commons) Modern

	zeit/next.js canary	chibicode/next.js improve-link-documentation	Change
main-HASH.module.js gzip	4.1 kB	4.1 kB	✓
webpack-HASH..dule.js gzip	746 B	746 B	✓
4952ddcd88e7..dule.js gzip	5.56 kB	5.56 kB	✓
de003c3a9d30..dule.js gzip	15 kB	15 kB	✓
framework.HA..dule.js gzip	39.1 kB	39.1 kB	✓
Overall change	64.5 kB	64.5 kB	✓

Legacy Client Bundles (polyfills)

	zeit/next.js canary	chibicode/next.js improve-link-documentation	Change
polyfills-HASH.js gzip	4.76 kB	4.76 kB	✓
Overall change	4.76 kB	4.76 kB	✓

Client Pages

	zeit/next.js canary	chibicode/next.js improve-link-documentation	Change
_app.js gzip	1.15 kB	1.15 kB	✓
_error.js gzip	4.07 kB	4.07 kB	✓
hooks.js gzip	779 B	779 B	✓
index.js gzip	222 B	222 B	✓
link.js gzip	2.89 kB	2.89 kB	✓
routerDirect.js gzip	283 B	283 B	✓
withRouter.js gzip	282 B	282 B	✓
Overall change	9.68 kB	9.68 kB	✓

Client Pages Modern

	zeit/next.js canary	chibicode/next.js improve-link-documentation	Change
_app.module.js gzip	576 B	576 B	✓
_error.module.js gzip	3.06 kB	3.06 kB	✓
hooks.module.js gzip	371 B	371 B	✓
index.module.js gzip	212 B	212 B	✓
link.module.js gzip	2.46 kB	2.46 kB	✓
routerDirect..dule.js gzip	273 B	273 B	✓
withRouter.m..dule.js gzip	272 B	272 B	✓
Overall change	7.22 kB	7.22 kB	✓

Client Build Manifests

	zeit/next.js canary	chibicode/next.js improve-link-documentation	Change
_buildManifest.js gzip	61 B	61 B	✓
_buildManife..dule.js gzip	61 B	61 B	✓
Overall change	122 B	122 B	✓

Serverless bundles

	zeit/next.js canary	chibicode/next.js improve-link-documentation	Change
_error.js gzip	46.2 kB	46.2 kB	✓
hooks.html gzip	1.06 kB	1.06 kB	✓
index.js gzip	46.4 kB	46.4 kB	✓
link.js gzip	71.9 kB	71.9 kB	✓
routerDirect.js gzip	69.9 kB	69.9 kB	✓
withRouter.js gzip	69.9 kB	69.9 kB	✓
Overall change	305 kB	305 kB	✓

Commit: 14ec8ca

[timneutkens]

Looks great!