Use markdown syntax in mdx where possible

Closes #788

.eslintrc.js

@@ -43,8 +43,6 @@ module.exports = {
       },
       rules: {
         'no-irregular-whitespace': 'off',
-        'jsx-a11y/anchor-has-content': 'off',
-        'react/jsx-no-target-blank': 'off',
       },
     },
   ],

cli/lib/extract.js

@@ -37,6 +37,12 @@ const unpackTarball = async ({release, cwd, dir}) => {
         // the v6 version of the funding page has json not inside a code
         .replace(/(:\n\n)(\s{4}"funding": {)/g, '$1```json\n$2')
         .replace(/^(\s{4}]$)(\n\n)/gm, '$1\n```$2')
+        // anchor links to markdown. this regex does need to match spaces and newlines since the source markdown
+        // already has some links where attributes are separated by newlines
+        .replace(
+          /<a[\s\n]href="(.*?)"(?:[\s\n]target="_blank")?(?:[\s\n]rel="[a-z\s]+")?>(.*?)<\/a>/g,
+          (_, href, text) => `[${href}](${text.trim()})`,
+        )
     )
   }
 

content/cli/v10/commands/npm-audit.mdx

@@ -99,13 +99,13 @@ The `sig` is generated using the following template: `${package.name}@${package.
 
 Keys response:
 
-- `expires`: null or a simplified extended <a href="https://en.wikipedia.org/wiki/ISO_8601" target="_blank">ISO 8601 format</a>: `YYYY-MM-DDTHH:mm:ss.sssZ`
+- `expires`: null or a simplified extended [https://en.wikipedia.org/wiki/ISO_8601](ISO 8601 format): `YYYY-MM-DDTHH:mm:ss.sssZ`
 - `keydid`: sha256 fingerprint of the public key
 - `keytype`: only `ecdsa-sha2-nistp256` is currently supported by the npm CLI
 - `scheme`: only `ecdsa-sha2-nistp256` is currently supported by the npm CLI
 - `key`: base64 encoded public key
 
-See this <a href="https://registry.npmjs.org/-/npm/v1/keys" target="_blank">example key's response from the public npm registry</a>.
+See this [https://registry.npmjs.org/-/npm/v1/keys](example key's response from the public npm registry).
 
 ### Audit Endpoints
 

content/cli/v10/commands/npm-team.mdx

@@ -55,7 +55,7 @@ Teams must always be fully qualified with the organization/scope they belong to
 
 If you have two-factor authentication enabled in `auth-and-writes` mode, then you can provide a code from your authenticator with `[--otp <otpcode>]`. If you don't include this then you will be taken through a second factor flow based on your `authtype`.
 
-- create / destroy: Create a new team, or destroy an existing one. Note: You cannot remove the `developers` team, <a href="https://docs.npmjs.com/about-developers-team" target="_blank">learn more.</a>
+- create / destroy: Create a new team, or destroy an existing one. Note: You cannot remove the `developers` team, [https://docs.npmjs.com/about-developers-team](learn more.)
 
   Here's how to create a new team `newteam` under the `org` org:
 

content/cli/v10/commands/npm-unpublish.mdx

@@ -41,9 +41,7 @@ redirect_from:
 npm unpublish [<package-spec>]
 ```
 
-To learn more about how the npm registry treats unpublish, see our <a
-href="https://docs.npmjs.com/policies/unpublish" target="_blank"
-rel="noopener noreferrer"> unpublish policies</a>
+To learn more about how the npm registry treats unpublish, see our [https://docs.npmjs.com/policies/unpublish](unpublish policies)
 
 ### Warning
 

content/cli/v6/commands/npm-team.mdx

@@ -41,7 +41,7 @@ Teams must always be fully qualified with the organization/scope they belong to
 
 If you have two-factor authentication enabled in `auth-and-writes` mode, then you can provide a code from your authenticator with `[--otp <otpcode>]`. If you don't include this then you will be prompted.
 
-- create / destroy: Create a new team, or destroy an existing one. Note: You cannot remove the `developers` team, <a href="https://docs.npmjs.com/about-developers-team" target="_blank">learn more.</a>
+- create / destroy: Create a new team, or destroy an existing one. Note: You cannot remove the `developers` team, [https://docs.npmjs.com/about-developers-team](learn more.)
 - add / rm: Add a user to an existing team, or remove a user from a team they belong to.
 
 - ls: If performed on an organization name, will return a list of existing teams under that organization. If performed on a team, it will instead return a list of all users belonging to that particular team.

content/cli/v6/commands/npm-unpublish.mdx

@@ -45,7 +45,7 @@ If no version is specified, or if all versions are removed then the root package
 
 Even if a package version is unpublished, that specific name and version combination can never be reused. In order to publish the package again, a new version number must be used. If you unpublish the entire package, you may not publish any new versions of that package until 24 hours have passed.
 
-To learn more about how unpublish is treated on the npm registry, see our <a href="https://www.npmjs.com/policies/unpublish" target="_blank" rel="noopener noreferrer"> unpublish policies</a>.
+To learn more about how unpublish is treated on the npm registry, see our [https://www.npmjs.com/policies/unpublish](unpublish policies).
 
 ### See Also
 

content/cli/v7/commands/npm-team.mdx

@@ -41,7 +41,7 @@ Teams must always be fully qualified with the organization/scope they belong to
 
 If you have two-factor authentication enabled in `auth-and-writes` mode, then you can provide a code from your authenticator with `[--otp <otpcode>]`. If you don't include this then you will be prompted.
 
-- create / destroy: Create a new team, or destroy an existing one. Note: You cannot remove the `developers` team, <a href="https://docs.npmjs.com/about-developers-team" target="_blank">learn more.</a>
+- create / destroy: Create a new team, or destroy an existing one. Note: You cannot remove the `developers` team, [https://docs.npmjs.com/about-developers-team](learn more.)
 
   Here's how to create a new team `newteam` under the `org` org:
 

content/cli/v7/commands/npm-unpublish.mdx

@@ -21,9 +21,7 @@ redirect_from:
 
 ### Synopsis
 
-To learn more about how the npm registry treats unpublish, see our <a
-href="https://docs.npmjs.com/policies/unpublish" target="_blank"
-rel="noopener noreferrer"> unpublish policies</a>
+To learn more about how the npm registry treats unpublish, see our [https://docs.npmjs.com/policies/unpublish](unpublish policies)
 
 #### Unpublishing a single version of a package
 

content/cli/v8/commands/npm-audit.mdx

@@ -79,13 +79,13 @@ The `sig` is generated using the following template: `${package.name}@${package.
 
 Keys response:
 
-- `expires`: null or a simplified extended <a href="https://en.wikipedia.org/wiki/ISO_8601" target="_blank">ISO 8601 format</a>: `YYYY-MM-DDTHH:mm:ss.sssZ`
+- `expires`: null or a simplified extended [https://en.wikipedia.org/wiki/ISO_8601](ISO 8601 format): `YYYY-MM-DDTHH:mm:ss.sssZ`
 - `keydid`: sha256 fingerprint of the public key
 - `keytype`: only `ecdsa-sha2-nistp256` is currently supported by the npm CLI
 - `scheme`: only `ecdsa-sha2-nistp256` is currently supported by the npm CLI
 - `key`: base64 encoded public key
 
-See this <a href="https://registry.npmjs.org/-/npm/v1/keys" target="_blank">example key's response from the public npm registry</a>.
+See this [https://registry.npmjs.org/-/npm/v1/keys](example key's response from the public npm registry).
 
 ### Audit Endpoints
 

content/cli/v8/commands/npm-team.mdx

@@ -39,7 +39,7 @@ Teams must always be fully qualified with the organization/scope they belong to
 
 If you have two-factor authentication enabled in `auth-and-writes` mode, then you can provide a code from your authenticator with `[--otp <otpcode>]`. If you don't include this then you will be prompted.
 
-- create / destroy: Create a new team, or destroy an existing one. Note: You cannot remove the `developers` team, <a href="https://docs.npmjs.com/about-developers-team" target="_blank">learn more.</a>
+- create / destroy: Create a new team, or destroy an existing one. Note: You cannot remove the `developers` team, [https://docs.npmjs.com/about-developers-team](learn more.)
 
   Here's how to create a new team `newteam` under the `org` org:
 

content/cli/v8/commands/npm-unpublish.mdx

@@ -25,9 +25,7 @@ redirect_from:
 npm unpublish [<package-spec>]
 ```
 
-To learn more about how the npm registry treats unpublish, see our <a
-href="https://docs.npmjs.com/policies/unpublish" target="_blank"
-rel="noopener noreferrer"> unpublish policies</a>
+To learn more about how the npm registry treats unpublish, see our [https://docs.npmjs.com/policies/unpublish](unpublish policies)
 
 ### Warning
 

content/cli/v9/commands/npm-audit.mdx

@@ -83,13 +83,13 @@ The `sig` is generated using the following template: `${package.name}@${package.
 
 Keys response:
 
-- `expires`: null or a simplified extended <a href="https://en.wikipedia.org/wiki/ISO_8601" target="_blank">ISO 8601 format</a>: `YYYY-MM-DDTHH:mm:ss.sssZ`
+- `expires`: null or a simplified extended [https://en.wikipedia.org/wiki/ISO_8601](ISO 8601 format): `YYYY-MM-DDTHH:mm:ss.sssZ`
 - `keydid`: sha256 fingerprint of the public key
 - `keytype`: only `ecdsa-sha2-nistp256` is currently supported by the npm CLI
 - `scheme`: only `ecdsa-sha2-nistp256` is currently supported by the npm CLI
 - `key`: base64 encoded public key
 
-See this <a href="https://registry.npmjs.org/-/npm/v1/keys" target="_blank">example key's response from the public npm registry</a>.
+See this [https://registry.npmjs.org/-/npm/v1/keys](example key's response from the public npm registry).
 
 ### Audit Endpoints
 

content/cli/v9/commands/npm-team.mdx

@@ -39,7 +39,7 @@ Teams must always be fully qualified with the organization/scope they belong to
 
 If you have two-factor authentication enabled in `auth-and-writes` mode, then you can provide a code from your authenticator with `[--otp <otpcode>]`. If you don't include this then you will be taken through a second factor flow based on your `authtype`.
 
-- create / destroy: Create a new team, or destroy an existing one. Note: You cannot remove the `developers` team, <a href="https://docs.npmjs.com/about-developers-team" target="_blank">learn more.</a>
+- create / destroy: Create a new team, or destroy an existing one. Note: You cannot remove the `developers` team, [https://docs.npmjs.com/about-developers-team](learn more.)
 
   Here's how to create a new team `newteam` under the `org` org:
 

content/cli/v9/commands/npm-unpublish.mdx

@@ -25,9 +25,7 @@ redirect_from:
 npm unpublish [<package-spec>]
 ```
 
-To learn more about how the npm registry treats unpublish, see our <a
-href="https://docs.npmjs.com/policies/unpublish" target="_blank"
-rel="noopener noreferrer"> unpublish policies</a>
+To learn more about how the npm registry treats unpublish, see our [https://docs.npmjs.com/policies/unpublish](unpublish policies)
 
 ### Warning
 

content/getting-started/setting-up-your-npm-user-account/creating-a-new-npm-user-account.mdx

@@ -32,11 +32,11 @@ If you do not already have an npm user account, you can create an account in ord
 
 ## Testing your new account with npm login
 
-Use the <a href="https://docs.npmjs.com/cli/adduser">`npm login`</a> command to test logging in to your new account.
+Use the [`npm login`](https://docs.npmjs.com/cli/adduser) command to test logging in to your new account.
 
 <Note>
 
-**Note:** If you misspell your existing account username when you log in with the `npm login` command, you will create a new account with the misspelled name. For help with accidentally-created accounts, <a href="https://www.npmjs.com/support">contact npm Support</a>.
+**Note:** If you misspell your existing account username when you log in with the `npm login` command, you will create a new account with the misspelled name. For help with accidentally-created accounts, [contact npm Support](https://www.npmjs.com/support).
 
 </Note>
 

content/packages-and-modules/contributing-packages-to-the-registry/about-package-readme-files.mdx

@@ -14,7 +14,7 @@ An npm package README file must be in the root-level directory of the package.
 
 <Note>
 
-**Note:** The file extension `.md` indicates a Markdown file. For more information about Markdown, see the GitHub Guide "<a href="https://guides.github.com/features/mastering-markdown/#what">Mastering Markdown</a>".
+**Note:** The file extension `.md` indicates a Markdown file. For more information about Markdown, see the GitHub Guide "[Mastering Markdown](https://guides.github.com/features/mastering-markdown/#what)".
 
 </Note>
 

content/packages-and-modules/contributing-packages-to-the-registry/creating-and-publishing-private-packages.mdx

@@ -12,9 +12,9 @@ For more information on scopes and private packages, see "[About scopes][scopes]
 
 <Note>
 
-**Note:** Before you can publish private user-scoped npm packages, you must <a href="https://npmjs.com/signup">sign up</a> for a paid npm user account.
+**Note:** Before you can publish private user-scoped npm packages, you must [sign up](https://npmjs.com/signup) for a paid npm user account.
 
-Additionally, to publish private organization-scoped packages, you must <a href="https://npmjs.com/signup">create an npm user account</a>, then <a href="https://www.npmjs.com/signup?next=/org/create"> create a paid npm organization</a>.
+Additionally, to publish private organization-scoped packages, you must [create an npm user account](https://npmjs.com/signup), then [ create a paid npm organization](https://www.npmjs.com/signup?next=/org/create).
 
 </Note>
 
@@ -58,7 +58,7 @@ Additionally, to publish private organization-scoped packages, you must <a href=
      npm init --scope=@my-username
      ```
 
-6. Respond to the prompts to generate a <a href="https://docs.npmjs.com/about-package-json-and-package-lock-json-files">`package.json`</a> file. For help naming your package, see "[Package name guidelines][pkg-name]".
+6. Respond to the prompts to generate a [`package.json`](https://docs.npmjs.com/about-package-json-and-package-lock-json-files) file. For help naming your package, see "[Package name guidelines][pkg-name]".
 
 7. Create a [README file][readme-file] that explains what your package code is and how to use it.
 

content/packages-and-modules/contributing-packages-to-the-registry/creating-and-publishing-scoped-public-packages.mdx

@@ -10,9 +10,9 @@ For more information on scopes, see "[About scopes][scopes]".
 
 <Note>
 
-**Note:** Before you can publish user-scoped npm packages, you must <a href="https://www.npmjs.com/signup">sign up</a> for an npm user account.
+**Note:** Before you can publish user-scoped npm packages, you must [sign up](https://www.npmjs.com/signup) for an npm user account.
 
-Additionally, to publish organization-scoped packages, you must <a href="https://www.npmjs.com/signup">create an npm user account</a>, then <a href="https://www.npmjs.com/signup?next=/org/create">create an npm organization</a>.
+Additionally, to publish organization-scoped packages, you must [create an npm user account](https://www.npmjs.com/signup), then [create an npm organization](https://www.npmjs.com/signup?next=/org/create).
 
 </Note>
 
@@ -56,7 +56,7 @@ Additionally, to publish organization-scoped packages, you must <a href="https:/
      npm init --scope=@my-username
      ```
 
-6. Respond to the prompts to generate a <a href="https://docs.npmjs.com/about-package-json-and-package-lock-json-files">`package.json`</a> file. For help naming your package, see "[Package name guidelines][pkg-name]".
+6. Respond to the prompts to generate a [`package.json`](https://docs.npmjs.com/about-package-json-and-package-lock-json-files) file. For help naming your package, see "[Package name guidelines][pkg-name]".
 7. Create a [README file][readme-file] that explains what your package code is and how to use it.
 8. In your preferred text editor, write the code for your package.
 

content/packages-and-modules/contributing-packages-to-the-registry/creating-and-publishing-unscoped-public-packages.mdx

@@ -12,7 +12,7 @@ For more information on package scope, access, and visibility, see "[Package sco
 
 <Note>
 
-**Note:** Before you can publish public unscoped npm packages, you must <a href="https://www.npmjs.com/signup">sign up</a> for an npm user account.
+**Note:** Before you can publish public unscoped npm packages, you must [sign up](https://www.npmjs.com/signup) for an npm user account.
 
 </Note>
 
@@ -38,7 +38,7 @@ For more information on package scope, access, and visibility, see "[Package sco
    ```
 
 4. In the package root directory, run the `npm init` command.
-5. Respond to the prompts to generate a <a href="https://docs.npmjs.com/about-package-json-and-package-lock-json-files">`package.json`</a> file. For help naming your package, see "[Package name guidelines][pkg-name]".
+5. Respond to the prompts to generate a [`package.json`](https://docs.npmjs.com/about-package-json-and-package-lock-json-files) file. For help naming your package, see "[Package name guidelines][pkg-name]".
 6. Create a [README file][readme-file] that explains what your package code is and how to use it.
 7. In your preferred text editor, write the code for your package.
 

content/packages-and-modules/introduction-to-packages-and-modules/package-scope-access-level-and-visibility.mdx

@@ -6,7 +6,7 @@ Visibility of npm packages depends on the scope (namespace) in which the package
 
 <Note>
 
-**Note:** To create organization-scoped packages, you must first create an organization. For more information, see "<a href="https://docs.npmjs.com/creating-an-organization">Creating an organization</a>".
+**Note:** To create organization-scoped packages, you must first create an organization. For more information, see "[Creating an organization](https://docs.npmjs.com/creating-an-organization)".
 
 </Note>
 

content/packages-and-modules/securing-your-code/about-registry-signatures.mdx

@@ -18,7 +18,7 @@ The public npm registry is migrating away from the existing PGP signatures to EC
 
 Signature verification was previously a multi-step process involving the Keybase CLI, as well as manually retrieving and parsing the signature from the package metadata.
 
-Read more about <a href="/verifying-registry-signatures">migrating and verifying signatures</a> using the npm CLI.
+Read more about [migrating and verifying signatures](/verifying-registry-signatures) using the npm CLI.
 
 ## Supporting signatures on third-party registries
 
@@ -35,11 +35,11 @@ The npm CLI supports registry signatures and signing keys provided by any regist
   }],
 ```
 
-See this <a href="https://registry.npmjs.org/light-cycle/1.4.3" target="_blank">example of a signed package from the public npm registry</a>.
+See this [example of a signed package from the public npm registry](https://registry.npmjs.org/light-cycle/1.4.3).
 
 To generate the signature, sign the package name, version and tarball sha integrity: `${package.name}@${package.version}:${package.dist.integrity}`.
 
-The current best practice is to use a <a href="https://en.wikipedia.org/wiki/Key_management#Key_management_system" target="_blank">Key Management System</a> that does the signing operation on a <a href="https://en.wikipedia.org/wiki/Hardware_security_module" target="_blank">Hardware Security Module (HSM)</a> in order to not directly handle the private key part, which reduces the attack surface.
+The current best practice is to use a [Key Management System](https://en.wikipedia.org/wiki/Key_management#Key_management_system) that does the signing operation on a [Hardware Security Module (HSM)](https://en.wikipedia.org/wiki/Hardware_security_module) in order to not directly handle the private key part, which reduces the attack surface.
 
 The `keyid` must match one of the public signing keys below.
 
@@ -59,10 +59,10 @@ The `keyid` must match one of the public signing keys below.
 
 Keys response:
 
-- `expires`: null or a simplified extended <a href="https://en.wikipedia.org/wiki/ISO_8601" target="_blank">ISO 8601 format</a>: `YYYY-MM-DDTHH:mm:ss.sssZ`
+- `expires`: null or a simplified extended [ISO 8601 format](https://en.wikipedia.org/wiki/ISO_8601): `YYYY-MM-DDTHH:mm:ss.sssZ`
 - `keydid`: sha256 fingerprint of the public key
 - `keytype`: only `ecdsa-sha2-nistp256` is currently supported by the npm CLI
 - `scheme`: only `ecdsa-sha2-nistp256` is currently supported by the npm CLI
 - `key`: base64 encoded public key
 
-See this <a href="https://registry.npmjs.org/-/npm/v1/keys" target="_blank">example key's response from the public npm registry</a>.
+See this [example key's response from the public npm registry](https://registry.npmjs.org/-/npm/v1/keys).

content/packages-and-modules/securing-your-code/auditing-package-dependencies-for-security-vulnerabilities.mdx

@@ -16,7 +16,7 @@ A security audit is an assessment of package dependencies for security vulnerabi
 
 </Note>
 
-The <a href="https://docs.npmjs.com/cli/audit">`npm audit` command</a> submits a description of the dependencies configured in your package to your default registry and asks for a report of known vulnerabilities. `npm audit` checks direct dependencies, devDependencies, bundledDependencies, and optionalDependencies, but does not check peerDependencies.
+The [`npm audit` command](https://docs.npmjs.com/cli/audit) submits a description of the dependencies configured in your package to your default registry and asks for a report of known vulnerabilities. `npm audit` checks direct dependencies, devDependencies, bundledDependencies, and optionalDependencies, but does not check peerDependencies.
 
 `npm audit` automatically runs when you install a package with `npm install`. You can also run `npm audit` manually on your [locally installed packages](downloading-and-installing-packages-locally) to conduct a security audit of the package and produce a report of dependency vulnerabilities and, if available, suggested patches.