Refactor docs of packages

mdx-js · Oct 21, 2023 · 74aee56 · 74aee56 · vercel · Oct 21, 2023
1 parent fdfe17b
commit 74aee56
Show file tree

Hide file tree

Showing 46 changed files with 2,197 additions and 1,767 deletions.
diff --git a/docs/_asset/index.css b/docs/_asset/index.css
@@ -912,6 +912,16 @@ button.success {
   background-color: var(--fg);
 }
 
+details {
+  border: 1px solid var(--gray-2);
+  padding: 1ex;
+  border-radius: 3px;
+}
+
+details[open] {
+  padding: calc(1em + 1ex);
+}
+
 @media (prefers-color-scheme: dark) {
   :root {
     --white: #f0f6fc;
@@ -1095,6 +1105,10 @@ button.success {
     border-color: var(--green-5);
     color: var(--white);
   }
+
+  details {
+    border-color: var(--gray-6);
+  }
 }
 
 @media (min-width: 22em) {

diff --git a/docs/docs/extending-mdx.mdx b/docs/docs/extending-mdx.mdx
@@ -104,8 +104,8 @@ You can use this template:
 ## Using plugins
 
 Where to pass plugins is encoded in their name: remark plugins go in
-[`options.remarkPlugins`][options-remark-plugins], rehype plugins
-in [`options.rehypePlugins`][options-rehype-plugins].
+`remarkPlugins` and rehype plugins go in `rehypePlugins` of
+[`ProcessorOptions`][processor-options].
 Those fields expect lists of plugins and/or of `[plugin, options]`:
 
 ```tsx
@@ -169,9 +169,7 @@ For info on the node types that represent MDX specific features, see
 
 [start]: /docs/getting-started/
 
-[options-remark-plugins]: /packages/mdx/#optionsremarkplugins
-
-[options-rehype-plugins]: /packages/mdx/#optionsrehypeplugins
+[processor-options]: /packages/mdx/#processoroptions
 
 [architecture]: /packages/mdx/#architecture
 

diff --git a/docs/docs/getting-started.mdx b/docs/docs/getting-started.mdx
@@ -108,28 +108,31 @@ your JSX runtime.
     you don’t need to do anything.
     Optionally install and configure [`@mdx-js/react`][mdx-react]
 *   If you’re using **Preact**,
-    set [`options.jsxImportSource`][options-jsximportsource] to `'preact'`.
+    set [`jsxImportSource` in `ProcessorOptions`][processor-options] to
+    `'preact'`.
     Optionally install and configure [`@mdx-js/preact`][mdx-preact]
 *   If you’re using **Svelte**,
     install [`svelte-jsx`][svelte-jsx].
-    Set [`options.jsxImportSource`][options-jsximportsource] to `'svelte-jsx'`.
+    Set [`jsxImportSource` in `ProcessorOptions`][processor-options] to
+    `'svelte-jsx'`.
 *   If you’re using **Vue 3**,
-    set [`options.jsx`][options-jsx] to `true`.
+    set [`jsx` in `ProcessorOptions`][processor-options] to `true`.
     Then use Babel alongside your MDX integration (which is possible with
     webpack and Rollup but not esbuild) and configure it to use
     [`@vue/babel-plugin-jsx`](https://github.com/vuejs/jsx-next/tree/dev/packages/babel-plugin-jsx).
     Optionally install and configure [`@mdx-js/vue`][mdx-vue]
 *   If you’re using **Emotion**,
-    set [`options.jsxImportSource`][options-jsximportsource] to
+    set [`jsxImportSource` in `ProcessorOptions`][processor-options] to
     `'@emotion/react'`
 *   If you’re using **Theme UI**,
     install and configure [`@mdx-js/react`][mdx-react].
     Then wrap your MDX content in a `<ThemeProvider />`
 *   If you’re using **Solid**,
-    set [`options.jsxImportSource`][options-jsximportsource] to `'solid-js/h'`
+    set [`jsxImportSource` in `ProcessorOptions`][processor-options] to
+    `'solid-js/h'`
 
 Other JSX runtimes are supported by setting
-[`options.jsxImportSource`][options-jsximportsource].
+[`jsxImportSource` in `ProcessorOptions`][processor-options].
 See also the different options there on how to use the classic JSX runtime
 and how to define a `pragma` and `pragmaFrag` for it.
 
@@ -719,7 +722,7 @@ on how to use MDX with React Static.
 </details>
 
 [Emotion](https://emotion.sh/docs/introduction) is supported when
-[`options.jsxImportSource`][options-jsximportsource] is set to
+[`jsxImportSource` in `ProcessorOptions`][processor-options] is set to
 `'@emotion/react'`.
 You can optionally install and configure [`@mdx-js/react`][mdx-react], which
 allows for context based component passing.
@@ -780,8 +783,8 @@ more info.
   ```
 </details>
 
-Preact is supported when [`options.jsxImportSource`][options-jsximportsource] is
-set to `'preact'`.
+Preact is supported when [`jsxImportSource` in `ProcessorOptions`][processor-options]
+is set to `'preact'`.
 You can optionally install and configure [`@mdx-js/preact`][mdx-preact], which
 allows for context based component passing.
 
@@ -856,8 +859,8 @@ info.
   ```
 </details>
 
-Svelte is supported when [`options.jsxImportSource`][options-jsximportsource] is
-set to `'svelte-jsx'`, which is a [small package][svelte-jsx] that adds support
+Svelte is supported when [`jsxImportSource` in `ProcessorOptions`][processor-options]
+is set to `'svelte-jsx'`, which is a [small package][svelte-jsx] that adds support
 for the JSX automatic runtime to Svelte.
 
 See also [¶ esbuild][esbuild], [¶ Rollup][rollup], and [¶ webpack][webpack],
@@ -899,8 +902,8 @@ for more info.
   ```
 </details>
 
-Solid is supported when [`options.jsxImportSource`][options-jsximportsource] is
-set to `'solid-js/h'`.
+Solid is supported when [`jsxImportSource` in `ProcessorOptions`][processor-options]
+is set to `'solid-js/h'`.
 
 See also [¶ Vite][vite] and [¶ Rollup][rollup] which you might be using, for
 more info.
@@ -961,9 +964,7 @@ See their readmes on how to configure them.
 
 [evaluate]: /packages/mdx/#evaluatefile-options
 
-[options-jsximportsource]: /packages/mdx/#optionsjsximportsource
-
-[options-jsx]: /packages/mdx/#optionsjsx
+[processor-options]: /packages/mdx/#processoroptions
 
 [cra]: #create-react-app-cra
 

diff --git a/docs/docs/using-mdx.mdx b/docs/docs/using-mdx.mdx
@@ -377,7 +377,7 @@ Set it up like so:
     or [`@mdx-js/vue`][mdx-vue],
     depending on what framework you’re using
 2.  Configure your MDX integration with
-    [`options.providerImportSource`][options-provider-import-source]
+    [`providerImportSource` in `ProcessorOptions`][processor-options]
     set to that package, so either `'@mdx-js/react'`, `'@mdx-js/preact'`, or
     `'@mdx-js/vue'`
 3.  Import `MDXProvider` from that package.
@@ -478,7 +478,7 @@ providers: pass components explicitly.
 
 [mdx-vue]: /packages/vue/
 
-[options-provider-import-source]: /packages/mdx/#optionsproviderimportsource
+[processor-options]: /packages/mdx/#processoroptions
 
 [emotion]: /docs/getting-started/#emotion
 

diff --git a/docs/docs/what-is-mdx.mdx b/docs/docs/what-is-mdx.mdx
@@ -78,7 +78,7 @@ in braces (`{1 + 1}`) and ESM (`import` and `export`).
   Or use it always.
   If you’re using a bundler integration you can change between MDX and
   markdown through the file extension (`.mdx` vs. `.md`).
-  Alternatively, [`options.format`][format] can be used.
+  Alternatively, `options.format` can be used.
 </Note>
 
 The MDX syntax combines markdown with JSX.
@@ -347,8 +347,6 @@ the heading.
 
 [jsx-spec]: https://facebook.github.io/jsx/
 
-[format]: /packages/mdx/#optionsformat
-
 [start]: /docs/getting-started/
 
 [trouble]: /docs/troubleshooting-mdx/

diff --git a/docs/guides/frontmatter.mdx b/docs/guides/frontmatter.mdx
@@ -87,8 +87,8 @@ title: Hi, World!
 That’s exactly what the remark plugin
 [`remark-mdx-frontmatter`][remark-mdx-frontmatter] does.
 
-remark plugins can be passed in
-[`options.remarkPlugins`][options-remark-plugins].
+remark plugins can be passed as
+[`remarkPlugins` in `ProcessorOptions`][processor-options].
 More info on plugins is available in [§ Extending MDX][extend]
 
 [commonmark]: https://spec.commonmark.org/current/
@@ -97,6 +97,6 @@ More info on plugins is available in [§ Extending MDX][extend]
 
 [remark-mdx-frontmatter]: https://github.com/remcohaszing/remark-mdx-frontmatter
 
-[options-remark-plugins]: /packages/mdx/#optionsremarkplugins
+[processor-options]: /packages/mdx/#processoroptions
 
 [extend]: /docs/extending-mdx/
diff --git a/docs/guides/gfm.mdx b/docs/guides/gfm.mdx
@@ -15,7 +15,8 @@ MDX supports standard markdown syntax ([CommonMark][]).
 That means [GitHub flavored markdown (GFM)][gfm] extensions are not supported by
 default.
 They can be enabled by using a remark plugin: [`remark-gfm`][remark-gfm].
-Such plugins can be passed in [`options.remarkPlugins`][options-remark-plugins].
+Such plugins can be passed in [`remarkPlugins` in
+`ProcessorOptions`][processor-options].
 More info on plugins is available in [§ Extending MDX][extend]
 
 Say we have an MDX file like this:
@@ -121,6 +122,6 @@ console.log(
 
 [remark-gfm]: https://github.com/remarkjs/remark-gfm
 
-[options-remark-plugins]: /packages/mdx/#optionsremarkplugins
+[processor-options]: /packages/mdx/#processoroptions
 
 [extend]: /docs/extending-mdx/
diff --git a/docs/guides/math.mdx b/docs/guides/math.mdx
@@ -18,9 +18,8 @@ Math can be enabled by using a remark plugin: [`remark-math`][remark-math],
 combined with a rehype plugin: either
 [`rehype-katex`][rehype-katex] (KaTeX) or [`rehype-mathjax`][rehype-mathjax]
 (MathJax).
-remark plugins can be passed in
-[`options.remarkPlugins`][options-remark-plugins] and rehype
-plugins in [`options.rehypePlugins`][options-rehype-plugins].
+Plugins can be passed in
+[`rehypePlugins` and `remarkPlugins` in `ProcessorOptions`][processor-options].
 More info on plugins is available in [§ Extending MDX][extend]
 
 Say we have an MDX file like this:
@@ -93,9 +92,7 @@ console.log(
 
 [rehype-mathjax]: https://github.com/remarkjs/remark-math/tree/main/packages/rehype-mathjax
 
-[options-remark-plugins]: /packages/mdx/#optionsremarkplugins
-
-[options-rehype-plugins]: /packages/mdx/#optionsrehypeplugins
+[processor-options]: /packages/mdx/#processoroptions
 
 [extend]: /docs/extending-mdx/
 

diff --git a/docs/guides/mdx-on-demand.mdx b/docs/guides/mdx-on-demand.mdx
@@ -105,6 +105,6 @@ export async function getStaticProps() {
 
 [compile]: /packages/mdx/#compilefile-options
 
-[run]: /packages/mdx/#runfunctionbody-options
+[run]: /packages/mdx/#runcode-options
 
 [eval]: /packages/mdx/#evaluatefile-options
diff --git a/docs/migrating/v2.mdx b/docs/migrating/v2.mdx
@@ -204,10 +204,8 @@ For more information, please see [§ API in `@mdx-js/loader`][loader-api].
 
 The options accepted by the loader changed:
 
-*   `renderer` is replaced by
-    [`options.jsxImportSource`][mdx-options-jsximportsource],
-    [`options.providerImportSource`][mdx-options-providerimportsource],
-    and others options.
+*   `renderer` is replaced by `jsxImportSource`, `providerImportSource`, and
+    others options.
     More info in [§ API in `@mdx-js/mdx`][mdx-api]
 *   Other options were undocumented but passed to `@mdx-js/mdx`.
     See `@mdx-js/mdx` below if needed
@@ -326,13 +324,10 @@ Options in version 1 were undocumented.
 If you used them:
 
 *   `filepath` is replaced by accepting a VFile or compatible object as the
-    first argument [`file`][mdx-file]
-*   `compilers` is replaced by
-    [`options.recmaPlugins`][mdx-options-recmaplugins]
-*   `hastPlugins` is replaced by
-    [`options.rehypePlugins`][mdx-options-rehypeplugins]
-*   `mdPlugins` is replaced by
-    [`options.remarkPlugins`][mdx-options-remarkplugins]
+    first argument `file`
+*   `compilers` is replaced by `recmaPlugins`
+*   `hastPlugins` is replaced by `rehypePlugins`
+*   `mdPlugins` is replaced by `options.remarkPlugins`
 *   `skipExport` is removed, [`evaluate`][mdx-evaluate] can do this
     automatically
 *   `wrapExport` is removed, use a custom recma plugin instead
@@ -666,15 +661,15 @@ With our new AST, we’re able to create codemods from now on.
 
 [remark-mdx-use]: /packages/remark-mdx/#use
 
-[mdx-compile]: /packages/mdx/#compile
+[mdx-compile]: /packages/mdx/#compilefile-options
 
-[mdx-compilesync]: /packages/mdx/#compilesync
+[mdx-compilesync]: /packages/mdx/#compilesyncfile-options
 
-[mdx-createprocessor]: /packages/mdx/#createprocessor
+[mdx-createprocessor]: /packages/mdx/#createprocessoroptions
 
-[mdx-evaluate]: /packages/mdx/#evaluate
+[mdx-evaluate]: /packages/mdx/#evaluatefile-options
 
-[mdx-evaluatesync]: /packages/mdx/#evaluatesync
+[mdx-evaluatesync]: /packages/mdx/#evaluatesyncfile-options
 
 [mdx-react]: /packages/react/
 
@@ -686,18 +681,6 @@ With our new AST, we’re able to create codemods from now on.
 
 [vfile]: https://github.com/vfile/vfile
 
-[mdx-file]: /packages/mdx/#file
-
-[mdx-options-recmaplugins]: /packages/mdx/#optionsrecmaplugins
-
-[mdx-options-remarkplugins]: /packages/mdx/#optionsremarkplugins
-
-[mdx-options-rehypeplugins]: /packages/mdx/#optionsrehypeplugins
-
-[mdx-options-jsximportsource]: /packages/mdx/#optionsjsximportsource
-
-[mdx-options-providerimportsource]: /packages/mdx/#optionsproviderimportsource
-
 [babel-loader]: https://webpack.js.org/loaders/babel-loader/
 
 [loader-api]: /packages/loader/#api