add @theguild/remark-npm2yarn package (#2056)

.changeset/chilled-months-remain.md

@@ -0,0 +1,13 @@
+---
+'nextra': minor
+'nextra-theme-blog': minor
+'nextra-theme-docs': minor
+---
+
+- add `@theguild/remark-npm2yarn` package that replaces the code block that has `npm2yarn` metadata
+  with `<Tabs />` and `<Tab />` components from `nextra/components`.
+
+- `<Tabs />` now has `selectedKey` prop, the chosen tab is saved in the local storage, which will be
+  chosen in future page renders.
+
+More info https://nextra.site/docs/guide/advanced/npm2yarn

.prettierignore

@@ -11,9 +11,7 @@ packages/nextra/__test__/locale-with-base-path.test.ts
 
 # bellow files are broken since prettier doesn't support MDX2
 examples/swr-site/pages/remote/graphql-eslint/\[\[...slug\]\].mdx
-docs/pages/docs/blog-theme/start.mdx
-docs/pages/docs/docs-theme/start.mdx
 examples/docs/src/pages/themes/docs/index.mdx
 examples/docs/src/pages/get-started.mdx
 examples/swr-site/pages/blog.en-US.mdx
-docs/pages/docs/guide/latex.mdx
+docs/pages/docs/guide/advanced/latex.mdx

docs/next.config.mjs

@@ -17,6 +17,11 @@ export default withNextra({
     ignoreDuringBuilds: true
   },
   redirects: () => [
+    {
+      source: '/docs/guide/:slug(typescript|latex|tailwind-css|mermaid)',
+      destination: '/docs/guide/advanced/:slug',
+      permanent: true
+    },
     {
       source: '/docs/docs-theme/built-ins/:slug(callout|steps|tabs)',
       destination: '/docs/guide/built-ins/:slug',

docs/pages/docs/blog-theme/start.mdx

@@ -1,4 +1,4 @@
-import { Callout, Tab, Tabs, Steps } from 'nextra/components'
+import { Callout, Steps } from 'nextra/components'
 
 # Get Started
 
@@ -8,7 +8,8 @@ import { Callout, Tab, Tabs, Steps } from 'nextra/components'
   An example of the blog theme can be found [here](https://demo.vercel.blog).
 </Callout>
 
-Similar to the [Docs Theme](/docs/docs-theme/start), you can install the blog theme with the following commands:
+Similar to the [Docs Theme](/docs/docs-theme/start), you can install the blog
+theme with the following commands:
 
 ## Quick Start from Template
 
@@ -17,25 +18,13 @@ Similar to the [Docs Theme](/docs/docs-theme/start), you can install the blog th
 <Steps>
 ### Install
 
-To create a Nextra Docs site manually, you have to install **Next.js**, **React**, **Nextra**, and **Nextra Blog Theme**. In your project directory, run the following command to install the dependencies:
-
-<Tabs items={['pnpm', 'npm', 'yarn']}>
-  <Tab>
-    ```bash
-    pnpm i next react react-dom nextra nextra-theme-blog
-    ```
-  </Tab>
-  <Tab>
-    ```bash
-    npm i next react react-dom nextra nextra-theme-blog
-    ```
-  </Tab>
-  <Tab>
-    ```bash
-    yarn add next react react-dom nextra nextra-theme-blog
-    ```
-  </Tab>
-</Tabs>
+To create a Nextra Docs site manually, you have to install **Next.js**,
+**React**, **Nextra**, and **Nextra Blog Theme**. In your project directory, run
+the following command to install the dependencies:
+
+```sh npm2yarn
+npm i next react react-dom nextra nextra-theme-blog
+```
 
 <Callout>
   If you already have Next.js installed in your project, you only need to
@@ -58,11 +47,14 @@ module.exports = withNextra()
 // module.exports = withNextra({ /* other next.js config */ })
 ```
 
-With the above configuration, Nextra can handle Markdown files in your Next.js project, with the specified theme. Other Nextra configurations can be found in [Guide](/docs/guide).
+With the above configuration, Nextra can handle Markdown files in your Next.js
+project, with the specified theme. Other Nextra configurations can be found in
+[Guide](/docs/guide).
 
 ### Create Blog Theme Config
 
-Lastly, create the corresponding `theme.config.jsx` file in your project’s root directory. This will be used to configure the Nextra Blog theme:
+Lastly, create the corresponding `theme.config.jsx` file in your project’s root
+directory. This will be used to configure the Nextra Blog theme:
 
 ```jsx filename="theme.config.jsx"
 export default {

docs/pages/docs/docs-theme/start.mdx

@@ -1,5 +1,5 @@
 import { BoxIcon, GearIcon, RowsIcon } from '@components/icons'
-import { Callout, Card, Cards, Steps, Tab, Tabs } from 'nextra/components'
+import { Callout, Card, Cards, Steps } from 'nextra/components'
 
 # Docs Theme
 
@@ -13,7 +13,8 @@ This website itself is built with the Nextra Docs Theme.
 
 ### Deploy to Vercel
 
-You can start by creating your own Nextra site and deploying to Vercel by clicking the link:
+You can start by creating your own Nextra site and deploying to Vercel by
+clicking the link:
 
 <a
   className="mt-3 inline-flex"
@@ -23,36 +24,28 @@ You can start by creating your own Nextra site and deploying to Vercel by clicki
   ![](https://vercel.com/button)
 </a>
 
-Vercel will fork the [Nextra Docs template](https://github.com/shuding/nextra-docs-template) and deploy the site for you. Once done, every commit in the repository will be deployed automatically.
+Vercel will fork the
+[Nextra Docs template](https://github.com/shuding/nextra-docs-template) and
+deploy the site for you. Once done, every commit in the repository will be
+deployed automatically.
 
 ### Fork the Template
 
-You can also manually fork the [template repository](https://github.com/shuding/nextra-docs-template).
+You can also manually fork the
+[template repository](https://github.com/shuding/nextra-docs-template).
 
 ## Start as New Project
 
 <Steps>
 ### Install
 
-To create a Nextra Docs site manually, you have to install **Next.js**, **React**, **Nextra**, and **Nextra Docs Theme**. In your project directory, run the following command to install the dependencies:
-
-<Tabs items={['pnpm', 'npm', 'yarn']}>
-  <Tab>
-    ```bash
-    pnpm i next react react-dom nextra nextra-theme-docs
-    ```
-  </Tab>
-  <Tab>
-    ```bash
-    npm i next react react-dom nextra nextra-theme-docs
-    ```
-  </Tab>
-  <Tab>
-    ```bash
-    yarn add next react react-dom nextra nextra-theme-docs
-    ```
-  </Tab>
-</Tabs>
+To create a Nextra Docs site manually, you have to install **Next.js**,
+**React**, **Nextra**, and **Nextra Docs Theme**. In your project directory, run
+the following command to install the dependencies:
+
+```sh npm2yarn
+npm i next react react-dom nextra nextra-theme-docs
+```
 
 <Callout>
   If you already have Next.js installed in your project, you only need to
@@ -75,11 +68,14 @@ module.exports = withNextra()
 // module.exports = withNextra({ /* other next.js config */ })
 ```
 
-With the above configuration, Nextra can handle Markdown files in your Next.js project, with the specified theme. Other Nextra configurations can be found in [Guide](/docs/guide).
+With the above configuration, Nextra can handle Markdown files in your Next.js
+project, with the specified theme. Other Nextra configurations can be found in
+[Guide](/docs/guide).
 
 ### Create Docs Theme Config
 
-Lastly, create the corresponding `theme.config.jsx` file in your project’s root directory. This will be used to configure the Nextra Docs theme:
+Lastly, create the corresponding `theme.config.jsx` file in your project’s root
+directory. This will be used to configure the Nextra Docs theme:
 
 ```jsx filename="theme.config.jsx"
 export default {
@@ -91,7 +87,8 @@ export default {
 }
 ```
 
-Full theme configurations can be found [here](/docs/docs-theme/theme-configuration).
+Full theme configurations can be found
+[here](/docs/docs-theme/theme-configuration).
 
 ### Ready to Go!
 
@@ -107,7 +104,8 @@ And run the `pnpm next` command to start developing the project! 🎉
 
 </Steps>
 
-Next, check out the next section to learn about organizing the documentation structure and configuring the website theme:
+Next, check out the next section to learn about organizing the documentation
+structure and configuring the website theme:
 
 <Cards>
   <Card

docs/pages/docs/guide/_meta.json

@@ -2,15 +2,11 @@
   "organize-files": "",
   "markdown": "",
   "syntax-highlighting": "",
-  "custom-css": "",
+  "link": "Next.js Link",
+  "image": "Next.js Image",
   "ssg": "Next.js SSG",
   "i18n": "Next.js I18n",
-  "image": "Next.js Image",
-  "link": "Next.js Link",
-  "latex": "LaTeX",
-  "mermaid": "",
-  "typescript": "",
-  "tailwind-css": "",
+  "custom-css": "",
   "advanced": "",
   "built-ins": "Built-ins"
 }

docs/pages/docs/guide/advanced/_meta.json

@@ -1,4 +1,9 @@
 {
+  "npm2yarn": "Npm2Yarn",
+  "mermaid": "",
+  "tailwind-css": "",
+  "latex": "LaTeX",
   "table": "Rendering Tables",
+  "typescript": "",
   "remote": "Remote Content"
 }

docs/pages/docs/guide/advanced/npm2yarn.mdx

@@ -0,0 +1,24 @@
+# Npm2Yarn
+
+Nextra uses
+[`@theguild/remark-npm2yarn`](https://npmjs.com/package/@theguild/remark-npm2yarn)
+package that replaces the code block that has `npm2yarn` metadata with
+[`<Tabs />` and `<Tab />` components](/docs/guide/built-ins/tabs) from
+`nextra/components`.
+
+The chosen tab is saved in the local storage, which will be chosen in future
+page renders.
+
+## Example
+
+```sh npm2yarn
+npm i -D @graphql-eslint/eslint-plugin
+```
+
+## Usage
+
+````mdx filename="Markdown" /npm2yarn/
+```sh npm2yarn
+npm i -D @graphql-eslint/eslint-plugin
+```
+````

docs/pages/docs/guide/advanced/table.mdx

@@ -178,8 +178,8 @@ HTML elements for your tables, do the following:
 <Steps>
 ### Install `remark-mdx-disable-explicit-jsx` package
 
-```sh
-pnpm add remark-mdx-disable-explicit-jsx
+```sh npm2yarn
+npm i remark-mdx-disable-explicit-jsx
 ```
 
 ### Setup

packages/nextra/package.json

@@ -127,6 +127,7 @@
     "@mdx-js/react": "^2.3.0",
     "@napi-rs/simple-git": "^0.1.8",
     "@theguild/remark-mermaid": "^0.0.4",
+    "@theguild/remark-npm2yarn": "^0.1.1",
     "clsx": "^1.2.1",
     "github-slugger": "^2.0.0",
     "graceful-fs": "^4.2.11",

packages/nextra/src/compile.ts

@@ -4,6 +4,7 @@ import type { ProcessorOptions } from '@mdx-js/mdx'
 import { createProcessor } from '@mdx-js/mdx'
 import type { Processor } from '@mdx-js/mdx/lib/core'
 import { remarkMermaid } from '@theguild/remark-mermaid'
+import { remarkNpm2Yarn } from '@theguild/remark-npm2yarn'
 import grayMatter from 'gray-matter'
 import rehypeKatex from 'rehype-katex'
 import type { Options as RehypePrettyCodeOptions } from 'rehype-pretty-code'
@@ -148,6 +149,14 @@ export async function compileMdx(
       remarkPlugins: [
         ...(remarkPlugins || []),
         remarkMermaid, // should be before remarkRemoveImports because contains `import { Mermaid } from ...`
+        [
+          remarkNpm2Yarn, // should be before remarkRemoveImports because contains `import { Tabs as $Tabs, Tab as $Tab } from ...`
+          {
+            packageName: 'nextra/components',
+            tabNamesProp: 'items',
+            storageKey: 'selectedPackageManager'
+          }
+        ] satisfies Pluggable,
         outputFormat === 'function-body' && remarkRemoveImports,
         remarkGfm,
         remarkCustomHeadingId,