From f459b646fa3a56d3bc4468751612415d00c0b743 Mon Sep 17 00:00:00 2001 From: Titus Wormer Date: Fri, 18 Oct 2024 17:11:51 +0200 Subject: [PATCH] Refactor docs --- docs/community/about.mdx | 7 +------ docs/docs/extending-mdx.mdx | 23 ++++++++++++++--------- docs/docs/getting-started.mdx | 7 +++---- docs/docs/using-mdx.mdx | 11 ++--------- docs/table-of-components.mdx | 6 +++--- 5 files changed, 23 insertions(+), 31 deletions(-) diff --git a/docs/community/about.mdx b/docs/community/about.mdx index 1dfb044b4..99a535ebf 100644 --- a/docs/community/about.mdx +++ b/docs/community/about.mdx @@ -4,7 +4,7 @@ export const info = { author: [ {github: 'wooorm', name: 'Titus Wormer', twitter: 'wooorm'} ], - modified: new Date('2021-11-01'), + modified: new Date('2024-10-18'), published: new Date('2021-10-06') } export const navSortSelf = 4 @@ -82,11 +82,6 @@ this project! The following projects, languages, and articles helped shape MDX either in implementation or inspiration. - - **Note**: Is your work missing? - Please open a PR if we failed to attribute your work. - - The [markdown][] and [JSX][] languages inspired MDX. Markdown was [created by John Gruber][markdown] (**[@gruber][gruber]**). [CommonMark][], the most popular markdown variant, by John McFarlane diff --git a/docs/docs/extending-mdx.mdx b/docs/docs/extending-mdx.mdx index 7935de425..a832be64b 100644 --- a/docs/docs/extending-mdx.mdx +++ b/docs/docs/extending-mdx.mdx @@ -4,7 +4,7 @@ export const info = { author: [ {github: 'wooorm', name: 'Titus Wormer', twitter: 'wooorm'} ], - modified: new Date('2024-07-04'), + modified: new Date('2024-10-18'), published: new Date('2021-10-06') } export const navSortSelf = 4 @@ -31,8 +31,8 @@ integrations: * Options passed to the compiler (see [¶ API in `@mdx-js/mdx`][api]) * Plugins that hook into several stages of compilation (see [remark - plugins][remark-plugins], [rehype plugins][rehype-plugins], and the new - recma plugins) + plugins][remark-plugins], [rehype plugins][rehype-plugins], and + [recma plugins][recma-plugins]) * Components passed, defined, or imported at runtime (see [§ Using MDX][use]) Most of the time, these components and plugins are not coupled to MDX. @@ -68,8 +68,9 @@ We’re compiling those here on this page. ### List of plugins -See also the [list of remark plugins][remark-plugins] and -[list of rehype plugins][rehype-plugins]. +See also the [list of remark plugins][remark-plugins], +[list of rehype plugins][rehype-plugins], and +[list of recma plugins][recma-plugins]. * [`remcohaszing/recma-export-filepath`](https://github.com/remcohaszing/recma-export-filepath) — export the filepath @@ -116,8 +117,10 @@ See also the [list of remark plugins][remark-plugins] and ## Using plugins -Where to pass plugins is encoded in their name: remark plugins go in -`remarkPlugins` and rehype plugins go in `rehypePlugins` of +Where to pass plugins is encoded in their name: +remark plugins go in `remarkPlugins`, +rehype plugins go in `rehypePlugins`, +and recma plugins go in `recmaPlugins` of [`ProcessorOptions`][processor-options]. Those fields expect lists of plugins and/or of `[plugin, options]`: @@ -155,8 +158,8 @@ await compile(file, { ## Creating plugins -Creating a plugin for MDX is mostly the same as creating a plugin for remark -or rehype. +Creating a plugin for MDX is mostly the same as creating a plugin for remark, +rehype, or recma. There are several guides and recipes on that in [§ Learn on `unifiedjs.com`][learn]. @@ -166,6 +169,8 @@ For info on the node types that represent MDX specific features, see [¶ Syntax tree in `remark-mdx`][syntax-tree] and use our interactive [§ Playground][playground]. +[recma-plugins]: https://github.com/mdx-js/recma/blob/main/doc/plugins.md#list-of-plugins + [remark-plugins]: https://github.com/remarkjs/remark/blob/main/doc/plugins.md#list-of-plugins [rehype-plugins]: https://github.com/rehypejs/rehype/blob/main/doc/plugins.md#list-of-plugins diff --git a/docs/docs/getting-started.mdx b/docs/docs/getting-started.mdx index e7bb7903e..7c746c963 100644 --- a/docs/docs/getting-started.mdx +++ b/docs/docs/getting-started.mdx @@ -4,7 +4,7 @@ export const info = { author: [ {github: 'wooorm', name: 'Titus Wormer', twitter: 'wooorm'} ], - modified: new Date('2024-07-04'), + modified: new Date('2024-10-18'), published: new Date('2021-10-05') } export const navSortSelf = 2 @@ -44,9 +44,8 @@ Note that we do compile JSX to JavaScript for you so you don’t have to set tha up. All `@mdx-js/*` packages are written in modern JavaScript. -A [Node.js][node-js] version of 16.0 or later is needed to use them. -Our packages are also [ESM only][github-gist-esm], -so they have to be `import`ed instead of `require`d. +A [Node.js][node-js] version of 16 or later is needed to use them. +Our packages are also [ESM only][github-gist-esm]. **Note**: Using Rust instead of Node.js? diff --git a/docs/docs/using-mdx.mdx b/docs/docs/using-mdx.mdx index 40f89dfcb..ed0ea2e60 100644 --- a/docs/docs/using-mdx.mdx +++ b/docs/docs/using-mdx.mdx @@ -4,7 +4,7 @@ export const info = { author: [ {github: 'wooorm', name: 'Titus Wormer', twitter: 'wooorm'} ], - modified: new Date('2024-07-04'), + modified: new Date('2024-10-18'), published: new Date('2021-09-30') } export const navSortSelf = 3 @@ -390,14 +390,7 @@ That’s because `a` is the HTML equivalent for the markdown syntax being used. The second link (`#bravo`) remains unchanged, because in JSX syntax `a` is a literal tag name. The third link (`#charlie`) is dashed and tomato, -as in JSX syntax `Link` is a reference. - - - **Note**: - Users of the MDX VS Code extension can add type - checking of provided and passed components with a JSDoc comment. - See [`mdx-js/mdx-analyzer`][mdx-analyzer] for more info. - +because in JSX syntax `Link` is a reference. ### Layout diff --git a/docs/table-of-components.mdx b/docs/table-of-components.mdx index 7ee31d418..05f33d934 100644 --- a/docs/table-of-components.mdx +++ b/docs/table-of-components.mdx @@ -3,7 +3,7 @@ export const info = { {github: 'johno', name: 'John Otander', twitter: '4lpine'}, {github: 'wooorm', name: 'Titus Wormer', twitter: 'wooorm'} ], - modified: new Date('2021-11-01'), + modified: new Date('2024-10-18'), published: new Date('2020-03-11') } export const navSortSelf = 4 @@ -105,7 +105,7 @@ More information on how to use markdown can be found in [CommonMark][]. ````mdx chrome=no Some `backticks` for inline. - ```tsx + ```javascript backtick.fences('for blocks') ``` ```` @@ -357,7 +357,7 @@ More information on how to use markdown can be found in [CommonMark][]. ````mdx chrome=no - ```tsx + ```javascript backtick.fences('for blocks') ``` ````