docs: safer documentation urls, repos, packages (#8030)

reggi · web-flow · commit 866b5ee3ae5e · 2025-01-14T09:26:50.000-08:00
Noticed some of the resources pointed to external sites not controlled
by npm or github and wanted to clean them up so they can't be squatted
on.
diff --git a/docs/lib/content/configuring-npm/package-json.md b/docs/lib/content/configuring-npm/package-json.md
@@ -47,7 +47,7 @@ Some tips:
   that name already, before you get too attached to it.
   <https://www.npmjs.com/>
 
-A name can be optionally prefixed by a scope, e.g. `@myorg/mypackage`. See
+A name can be optionally prefixed by a scope, e.g. `@npm/example`. See
 [`scope`](/using-npm/scope) for more detail.
 
 ### version
@@ -80,7 +80,7 @@ The URL to the project homepage.
 Example:
 
 ```json
-"homepage": "https://github.com/owner/project#readme"
+"homepage": "https://github.com/npm/example#readme"
 ```
 
 ### bugs
@@ -94,8 +94,8 @@ It should look like this:
 ```json
 {
   "bugs": {
-    "url": "https://github.com/owner/project/issues",
-    "email": "project@hostname.com"
+    "url": "https://github.com/npm/example/issues",
+    "email": "example@npmjs.com"
   }
 }
 ```
@@ -204,8 +204,8 @@ like this:
 ```json
 {
   "name" : "Barney Rubble",
-  "email" : "b@rubble.com",
-  "url" : "http://barnyrubble.tumblr.com/"
+  "email" : "barney@npmjs.com",
+  "url" : "http://barnyrubble.npmjs.com/"
 }
 ```
 
@@ -214,7 +214,7 @@ you:
 
 ```json
 {
-  "author": "Barney Rubble <b@rubble.com> (http://barnyrubble.tumblr.com/)"
+  "author": "Barney Rubble <barney@npmjs.com> (http://barnyrubble.npmjs.com/)"
 }
 ```
 
@@ -232,7 +232,7 @@ string URL, or an array of objects and string URLs:
 {
   "funding": {
     "type" : "individual",
-    "url" : "http://example.com/donate"
+    "url" : "http://npmjs.com/donate"
   }
 }
 ```
@@ -241,14 +241,14 @@ string URL, or an array of objects and string URLs:
 {
   "funding": {
     "type" : "patreon",
-    "url" : "https://www.patreon.com/my-account"
+    "url" : "https://www.patreon.com/user"
   }
 }
 ```
 
 ```json
 {
-  "funding": "http://example.com/donate"
+  "funding": "http://npmjs.com/donate"
 }
 ```
 
@@ -257,12 +257,12 @@ string URL, or an array of objects and string URLs:
   "funding": [
     {
       "type" : "individual",
-      "url" : "http://example.com/donate"
+      "url" : "http://npmjs.com/donate"
     },
-    "http://example.com/donateAlso",
+    "http://npmjs.com/donate-also",
     {
       "type" : "patreon",
-      "url" : "https://www.patreon.com/my-account"
+      "url" : "https://www.patreon.com/user"
     }
   ]
 }
@@ -539,9 +539,9 @@ same shortcut syntax you use for `npm install`:
 
 ```json
 {
-  "repository": "npm/npm",
+  "repository": "npm/example",
 
-  "repository": "github:user/repo",
+  "repository": "github:npm/example",
 
   "repository": "gist:11081aaa281",
 
@@ -635,7 +635,7 @@ For example, these are all valid:
     "baz": ">1.0.2 <=2.3.4",
     "boo": "2.0.1",
     "qux": "<1.0.0 || >=2.3.1 <2.4.5 || >=2.5.2 <3.0.0",
-    "asd": "http://asdf.com/asdf.tar.gz",
+    "asd": "http://npmjs.com/example.tar.gz",
     "til": "~1.2",
     "elf": "~1.2.3",
     "two": "2.x",
@@ -714,7 +714,7 @@ included.  For example:
   "dependencies": {
     "express": "expressjs/express",
     "mocha": "mochajs/mocha#4727d357ea",
-    "module": "user/repo#feature\/branch"
+    "module": "npm/example-github-repo#feature\/branch"
   }
 }
 ```
@@ -773,7 +773,7 @@ For example:
 
 ```json
 {
-  "name": "ethopia-waza",
+  "name": "@npm/ethopia-waza",
   "description": "a delightfully fruity coffee varietal",
   "version": "1.2.3",
   "devDependencies": {
@@ -803,21 +803,21 @@ For example:
 
 ```json
 {
-  "name": "tea-latte",
+  "name": "@npm/tea-latte",
   "version": "1.3.5",
   "peerDependencies": {
-    "tea": "2.x"
+    "@npm/tea": "2.x"
   }
 }
 ```
 
-This ensures your package `tea-latte` can be installed *along* with the
-second major version of the host package `tea` only. `npm install
+This ensures your package `@npm/tea-latte` can be installed *along* with the
+second major version of the host package `@npm/tea` only. `npm install
 tea-latte` could possibly yield the following dependency graph:
 
 ```bash
-├── tea-latte@1.3.5
-└── tea@2.2.0
+├── @npm/tea-latte@1.3.5
+└── @npm/tea@2.2.0
 ```
 
 In npm versions 3 through 6, `peerDependencies` were not automatically
@@ -849,14 +849,14 @@ For example:
 
 ```json
 {
-  "name": "tea-latte",
+  "name": "@npm/tea-latte",
   "version": "1.3.5",
   "peerDependencies": {
-    "tea": "2.x",
-    "soy-milk": "1.2"
+    "@npm/tea": "2.x",
+    "@npm/soy-milk": "1.2"
   },
   "peerDependenciesMeta": {
-    "soy-milk": {
+    "@npm/soy-milk": {
       "optional": true
     }
   }
@@ -879,17 +879,17 @@ If we define a package.json like this:
 
 ```json
 {
-  "name": "awesome-web-framework",
+  "name": "@npm/awesome-web-framework",
   "version": "1.0.0",
   "bundleDependencies": [
-    "renderized",
-    "super-streams"
+    "@npm/renderized",
+    "@npm/super-streams"
   ]
 }
 ```
 
-we can obtain `awesome-web-framework-1.0.0.tgz` file by running `npm pack`.
-This file contains the dependencies `renderized` and `super-streams` which
+we can obtain `@npm/awesome-web-framework-1.0.0.tgz` file by running `npm pack`.
+This file contains the dependencies `@npm/renderized` and `@npm/super-streams` which
 can be installed in a new project by executing `npm install
 awesome-web-framework-1.0.0.tgz`.  Note that the package names do not
 include any versions, as that information is specified in `dependencies`.
@@ -914,8 +914,8 @@ dependency.  For example, something like this:
 
 ```js
 try {
-  var foo = require('foo')
-  var fooVersion = require('foo/package.json').version
+  var foo = require('@npm/foo')
+  var fooVersion = require('@npm/foo/package.json').version
 } catch (er) {
   foo = null
 }
@@ -957,63 +957,63 @@ what version your dependencies rely on:
 ```json
 {
   "overrides": {
-    "foo": "1.0.0"
+    "@npm/foo": "1.0.0"
   }
 }
 ```
 
 The above is a short hand notation, the full object form can be used to allow
 overriding a package itself as well as a child of the package. This will cause
-`foo` to always be `1.0.0` while also making `bar` at any depth beyond `foo`
+`@npm/foo` to always be `1.0.0` while also making `@npm/bar` at any depth beyond `@npm/foo`
 also `1.0.0`:
 
 ```json
 {
   "overrides": {
-    "foo": {
+    "@npm/foo": {
       ".": "1.0.0",
-      "bar": "1.0.0"
+      "@npm/bar": "1.0.0"
     }
   }
 }
 ```
 
-To only override `foo` to be `1.0.0` when it's a child (or grandchild, or great
+To only override `@npm/foo` to be `1.0.0` when it's a child (or grandchild, or great
 grandchild, etc) of the package `bar`:
 
 ```json
 {
   "overrides": {
-    "bar": {
-      "foo": "1.0.0"
+    "@npm/bar": {
+      "@npm/foo": "1.0.0"
     }
   }
 }
 ```
 
-Keys can be nested to any arbitrary length. To override `foo` only when it's a
-child of `bar` and only when `bar` is a child of `baz`:
+Keys can be nested to any arbitrary length. To override `@npm/foo` only when it's a
+child of `@npm/bar` and only when `@npm/bar` is a child of `@npm/baz`:
 
 ```json
 {
   "overrides": {
-    "baz": {
-      "bar": {
-        "foo": "1.0.0"
+    "@npm/baz": {
+      "@npm/bar": {
+        "@npm/foo": "1.0.0"
       }
     }
   }
 }
 ```
 
 The key of an override can also include a version, or range of versions.
-To override `foo` to `1.0.0`, but only when it's a child of `bar@2.0.0`:
+To override `@npm/foo` to `1.0.0`, but only when it's a child of `@npm/bar@2.0.0`:
 
 ```json
 {
   "overrides": {
-    "bar@2.0.0": {
-      "foo": "1.0.0"
+    "@npm/bar@2.0.0": {
+      "@npm/foo": "1.0.0"
     }
   }
 }
@@ -1028,17 +1028,17 @@ package you wish the version to match with a `$`.
 ```json
 {
   "dependencies": {
-    "foo": "^1.0.0"
+    "@npm/foo": "^1.0.0"
   },
   "overrides": {
     // BAD, will throw an EOVERRIDE error
     // "foo": "^2.0.0"
     // GOOD, specs match so override is allowed
     // "foo": "^1.0.0"
     // BEST, the override is defined as a reference to the dependency
-    "foo": "$foo",
+    "@npm/foo": "$foo",
     // the referenced package does not need to match the overridden one
-    "bar": "$foo"
+    "@npm/bar": "$foo"
   }
 }
 ```

Original file line number	Diff line number	Diff line change
`@@ -47,7 +47,7 @@ Some tips:`
`47`	`47`	`that name already, before you get too attached to it.`
`48`	`48`	`<https://www.npmjs.com/>`
`49`	`49`
`50`		-A name can be optionally prefixed by a scope, e.g. `@myorg/mypackage`. See
	`50`	+A name can be optionally prefixed by a scope, e.g. `@npm/example`. See
`51`	`51`	[`scope`](/using-npm/scope) for more detail.
`52`	`52`
`53`	`53`	`### version`
`@@ -80,7 +80,7 @@ The URL to the project homepage.`
`80`	`80`	`Example:`
`81`	`81`
`82`	`82`	```json
`83`		`-"homepage": "https://github.com/owner/project#readme"`
	`83`	`+"homepage": "https://github.com/npm/example#readme"`
`84`	`84`	```
`85`	`85`
`86`	`86`	`### bugs`
`@@ -94,8 +94,8 @@ It should look like this:`
`94`	`94`	```json
`95`	`95`	`{`
`96`	`96`	`"bugs": {`
`97`		`- "url": "https://github.com/owner/project/issues",`
`98`		`- "email": "project@hostname.com"`
	`97`	`+ "url": "https://github.com/npm/example/issues",`
	`98`	`+ "email": "example@npmjs.com"`
`99`	`99`	`}`
`100`	`100`	`}`
`101`	`101`	```
`@@ -204,8 +204,8 @@ like this:`
`204`	`204`	```json
`205`	`205`	`{`
`206`	`206`	`"name" : "Barney Rubble",`
`207`		`- "email" : "b@rubble.com",`
`208`		`- "url" : "http://barnyrubble.tumblr.com/"`
	`207`	`+ "email" : "barney@npmjs.com",`
	`208`	`+ "url" : "http://barnyrubble.npmjs.com/"`
`209`	`209`	`}`
`210`	`210`	```
`211`	`211`
`@@ -214,7 +214,7 @@ you:`
`214`	`214`
`215`	`215`	```json
`216`	`216`	`{`
`217`		`- "author": "Barney Rubble <b@rubble.com> (http://barnyrubble.tumblr.com/)"`
	`217`	`+ "author": "Barney Rubble <barney@npmjs.com> (http://barnyrubble.npmjs.com/)"`
`218`	`218`	`}`
`219`	`219`	```
`220`	`220`
`@@ -232,7 +232,7 @@ string URL, or an array of objects and string URLs:`
`232`	`232`	`{`
`233`	`233`	`"funding": {`
`234`	`234`	`"type" : "individual",`
`235`		`- "url" : "http://example.com/donate"`
	`235`	`+ "url" : "http://npmjs.com/donate"`
`236`	`236`	`}`
`237`	`237`	`}`
`238`	`238`	```
`@@ -241,14 +241,14 @@ string URL, or an array of objects and string URLs:`
`241`	`241`	`{`
`242`	`242`	`"funding": {`
`243`	`243`	`"type" : "patreon",`
`244`		`- "url" : "https://www.patreon.com/my-account"`
	`244`	`+ "url" : "https://www.patreon.com/user"`
`245`	`245`	`}`
`246`	`246`	`}`
`247`	`247`	```
`248`	`248`
`249`	`249`	```json
`250`	`250`	`{`
`251`		`- "funding": "http://example.com/donate"`
	`251`	`+ "funding": "http://npmjs.com/donate"`
`252`	`252`	`}`
`253`	`253`	```
`254`	`254`
`@@ -257,12 +257,12 @@ string URL, or an array of objects and string URLs:`
`257`	`257`	`"funding": [`
`258`	`258`	`{`
`259`	`259`	`"type" : "individual",`
`260`		`- "url" : "http://example.com/donate"`
	`260`	`+ "url" : "http://npmjs.com/donate"`
`261`	`261`	`},`
`262`		`- "http://example.com/donateAlso",`
	`262`	`+ "http://npmjs.com/donate-also",`
`263`	`263`	`{`
`264`	`264`	`"type" : "patreon",`
`265`		`- "url" : "https://www.patreon.com/my-account"`
	`265`	`+ "url" : "https://www.patreon.com/user"`
`266`	`266`	`}`
`267`	`267`	`]`
`268`	`268`	`}`
@@ -539,9 +539,9 @@ same shortcut syntax you use for `npm install`:
`539`	`539`
`540`	`540`	```json
`541`	`541`	`{`
`542`		`- "repository": "npm/npm",`
	`542`	`+ "repository": "npm/example",`
`543`	`543`
`544`		`- "repository": "github:user/repo",`
	`544`	`+ "repository": "github:npm/example",`
`545`	`545`
`546`	`546`	`"repository": "gist:11081aaa281",`
`547`	`547`
`@@ -635,7 +635,7 @@ For example, these are all valid:`
`635`	`635`	`"baz": ">1.0.2 <=2.3.4",`
`636`	`636`	`"boo": "2.0.1",`
`637`	`637`	`"qux": "<1.0.0 \|\| >=2.3.1 <2.4.5 \|\| >=2.5.2 <3.0.0",`
`638`		`- "asd": "http://asdf.com/asdf.tar.gz",`
	`638`	`+ "asd": "http://npmjs.com/example.tar.gz",`
`639`	`639`	`"til": "~1.2",`
`640`	`640`	`"elf": "~1.2.3",`
`641`	`641`	`"two": "2.x",`
`@@ -714,7 +714,7 @@ included. For example:`
`714`	`714`	`"dependencies": {`
`715`	`715`	`"express": "expressjs/express",`
`716`	`716`	`"mocha": "mochajs/mocha#4727d357ea",`
`717`		`- "module": "user/repo#feature\/branch"`
	`717`	`+ "module": "npm/example-github-repo#feature\/branch"`
`718`	`718`	`}`
`719`	`719`	`}`
`720`	`720`	```
`@@ -773,7 +773,7 @@ For example:`
`773`	`773`
`774`	`774`	```json
`775`	`775`	`{`
`776`		`- "name": "ethopia-waza",`
	`776`	`+ "name": "@npm/ethopia-waza",`
`777`	`777`	`"description": "a delightfully fruity coffee varietal",`
`778`	`778`	`"version": "1.2.3",`
`779`	`779`	`"devDependencies": {`
`@@ -803,21 +803,21 @@ For example:`
`803`	`803`
`804`	`804`	```json
`805`	`805`	`{`
`806`		`- "name": "tea-latte",`
	`806`	`+ "name": "@npm/tea-latte",`
`807`	`807`	`"version": "1.3.5",`
`808`	`808`	`"peerDependencies": {`
`809`		`- "tea": "2.x"`
	`809`	`+ "@npm/tea": "2.x"`
`810`	`810`	`}`
`811`	`811`	`}`
`812`	`812`	```
`813`	`813`
`814`		-This ensures your package `tea-latte` can be installed along with the
`815`		-second major version of the host package `tea` only. `npm install
	`814`	+This ensures your package `@npm/tea-latte` can be installed along with the
	`815`	+second major version of the host package `@npm/tea` only. `npm install
`816`	`816`	tea-latte` could possibly yield the following dependency graph:
`817`	`817`
`818`	`818`	```bash
`819`		`-├── tea-latte@1.3.5`
`820`		`-└── tea@2.2.0`
	`819`	`+├── @npm/tea-latte@1.3.5`
	`820`	`+└── @npm/tea@2.2.0`
`821`	`821`	```
`822`	`822`
`823`	`823`	In npm versions 3 through 6, `peerDependencies` were not automatically
`@@ -849,14 +849,14 @@ For example:`
`849`	`849`
`850`	`850`	```json
`851`	`851`	`{`
`852`		`- "name": "tea-latte",`
	`852`	`+ "name": "@npm/tea-latte",`
`853`	`853`	`"version": "1.3.5",`
`854`	`854`	`"peerDependencies": {`
`855`		`- "tea": "2.x",`
`856`		`- "soy-milk": "1.2"`
	`855`	`+ "@npm/tea": "2.x",`
	`856`	`+ "@npm/soy-milk": "1.2"`
`857`	`857`	`},`
`858`	`858`	`"peerDependenciesMeta": {`
`859`		`- "soy-milk": {`
	`859`	`+ "@npm/soy-milk": {`
`860`	`860`	`"optional": true`
`861`	`861`	`}`
`862`	`862`	`}`
`@@ -879,17 +879,17 @@ If we define a package.json like this:`
`879`	`879`
`880`	`880`	```json
`881`	`881`	`{`
`882`		`- "name": "awesome-web-framework",`
	`882`	`+ "name": "@npm/awesome-web-framework",`
`883`	`883`	`"version": "1.0.0",`
`884`	`884`	`"bundleDependencies": [`
`885`		`- "renderized",`
`886`		`- "super-streams"`
	`885`	`+ "@npm/renderized",`
	`886`	`+ "@npm/super-streams"`
`887`	`887`	`]`
`888`	`888`	`}`
`889`	`889`	```
`890`	`890`
`891`		-we can obtain `awesome-web-framework-1.0.0.tgz` file by running `npm pack`.
`892`		-This file contains the dependencies `renderized` and `super-streams` which
	`891`	+we can obtain `@npm/awesome-web-framework-1.0.0.tgz` file by running `npm pack`.
	`892`	+This file contains the dependencies `@npm/renderized` and `@npm/super-streams` which
`893`	`893`	can be installed in a new project by executing `npm install
`894`	`894`	awesome-web-framework-1.0.0.tgz`. Note that the package names do not
`895`	`895`	include any versions, as that information is specified in `dependencies`.
`@@ -914,8 +914,8 @@ dependency. For example, something like this:`
`914`	`914`
`915`	`915`	```js
`916`	`916`	`try {`
`917`		`- var foo = require('foo')`
`918`		`- var fooVersion = require('foo/package.json').version`
	`917`	`+ var foo = require('@npm/foo')`
	`918`	`+ var fooVersion = require('@npm/foo/package.json').version`
`919`	`919`	`} catch (er) {`
`920`	`920`	`foo = null`
`921`	`921`	`}`
`@@ -957,63 +957,63 @@ what version your dependencies rely on:`
`957`	`957`	```json
`958`	`958`	`{`
`959`	`959`	`"overrides": {`
`960`		`- "foo": "1.0.0"`
	`960`	`+ "@npm/foo": "1.0.0"`
`961`	`961`	`}`
`962`	`962`	`}`
`963`	`963`	```
`964`	`964`
`965`	`965`	`The above is a short hand notation, the full object form can be used to allow`
`966`	`966`	`overriding a package itself as well as a child of the package. This will cause`
`967`		-`foo` to always be `1.0.0` while also making `bar` at any depth beyond `foo`
	`967`	+`@npm/foo` to always be `1.0.0` while also making `@npm/bar` at any depth beyond `@npm/foo`
`968`	`968`	also `1.0.0`:
`969`	`969`
`970`	`970`	```json
`971`	`971`	`{`
`972`	`972`	`"overrides": {`
`973`		`- "foo": {`
	`973`	`+ "@npm/foo": {`
`974`	`974`	`".": "1.0.0",`
`975`		`- "bar": "1.0.0"`
	`975`	`+ "@npm/bar": "1.0.0"`
`976`	`976`	`}`
`977`	`977`	`}`
`978`	`978`	`}`
`979`	`979`	```
`980`	`980`
`981`		-To only override `foo` to be `1.0.0` when it's a child (or grandchild, or great
	`981`	+To only override `@npm/foo` to be `1.0.0` when it's a child (or grandchild, or great
`982`	`982`	grandchild, etc) of the package `bar`:
`983`	`983`
`984`	`984`	```json
`985`	`985`	`{`
`986`	`986`	`"overrides": {`
`987`		`- "bar": {`
`988`		`- "foo": "1.0.0"`
	`987`	`+ "@npm/bar": {`
	`988`	`+ "@npm/foo": "1.0.0"`
`989`	`989`	`}`
`990`	`990`	`}`
`991`	`991`	`}`
`992`	`992`	```
`993`	`993`
`994`		-Keys can be nested to any arbitrary length. To override `foo` only when it's a
`995`		-child of `bar` and only when `bar` is a child of `baz`:
	`994`	+Keys can be nested to any arbitrary length. To override `@npm/foo` only when it's a
	`995`	+child of `@npm/bar` and only when `@npm/bar` is a child of `@npm/baz`:
`996`	`996`
`997`	`997`	```json
`998`	`998`	`{`
`999`	`999`	`"overrides": {`
`1000`		`- "baz": {`
`1001`		`- "bar": {`
`1002`		`- "foo": "1.0.0"`
	`1000`	`+ "@npm/baz": {`
	`1001`	`+ "@npm/bar": {`
	`1002`	`+ "@npm/foo": "1.0.0"`
`1003`	`1003`	`}`
`1004`	`1004`	`}`
`1005`	`1005`	`}`
`1006`	`1006`	`}`
`1007`	`1007`	```
`1008`	`1008`
`1009`	`1009`	`The key of an override can also include a version, or range of versions.`
`1010`		-To override `foo` to `1.0.0`, but only when it's a child of `bar@2.0.0`:
	`1010`	+To override `@npm/foo` to `1.0.0`, but only when it's a child of `@npm/bar@2.0.0`:
`1011`	`1011`
`1012`	`1012`	```json
`1013`	`1013`	`{`
`1014`	`1014`	`"overrides": {`
`1015`		`- "bar@2.0.0": {`
`1016`		`- "foo": "1.0.0"`
	`1015`	`+ "@npm/bar@2.0.0": {`
	`1016`	`+ "@npm/foo": "1.0.0"`
`1017`	`1017`	`}`
`1018`	`1018`	`}`
`1019`	`1019`	`}`
@@ -1028,17 +1028,17 @@ package you wish the version to match with a `$`.
`1028`	`1028`	```json
`1029`	`1029`	`{`
`1030`	`1030`	`"dependencies": {`
`1031`		`- "foo": "^1.0.0"`
	`1031`	`+ "@npm/foo": "^1.0.0"`
`1032`	`1032`	`},`
`1033`	`1033`	`"overrides": {`
`1034`	`1034`	`// BAD, will throw an EOVERRIDE error`
`1035`	`1035`	`// "foo": "^2.0.0"`
`1036`	`1036`	`// GOOD, specs match so override is allowed`
`1037`	`1037`	`// "foo": "^1.0.0"`
`1038`	`1038`	`// BEST, the override is defined as a reference to the dependency`
`1039`		`- "foo": "$foo",`
	`1039`	`+ "@npm/foo": "$foo",`
`1040`	`1040`	`// the referenced package does not need to match the overridden one`
`1041`		`- "bar": "$foo"`
	`1041`	`+ "@npm/bar": "$foo"`
`1042`	`1042`	`}`
`1043`	`1043`	`}`
`1044`	`1044`	```