From 8280b021fa990961cb20762a78f61bb043507209 Mon Sep 17 00:00:00 2001 From: Karl Horky Date: Mon, 8 Jul 2024 13:04:58 +0200 Subject: [PATCH 1/7] Add TypeScript `Props` Type section to Using MDX Signed-off-by: Karl Horky --- docs/docs/using-mdx.mdx | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/docs/docs/using-mdx.mdx b/docs/docs/using-mdx.mdx index 830f600db..b29e23cbd 100644 --- a/docs/docs/using-mdx.mdx +++ b/docs/docs/using-mdx.mdx @@ -206,6 +206,27 @@ console.log(React.createElement(Example, {name: 'Venus', year: 2021})) console.log() ``` +#### TypeScript: `Props` Type + +To declare a type for the `props` object, use the JSDoc `@typedef` tag: + +```mdx +{/** + * @typedef Props + * @property {string} name + * Who to greet. */} + +# Hello {props.name} +``` + +This will be used by [the MDX VS Code extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) to show JSDoc information and errors in IntelliSense hovers (see the [MDX Analyzer Props docs](https://github.com/mdx-js/mdx-analyzer#props) for more details): + +![Screenshot of MDX VS Code extension with `example.mdx` file open, showing mouse hovering over "name" in "props.name", with the IntelliSense hover card showing the details from the JSDoc type](https://github.com/mdx-js/mdx/assets/1935696/de2cdc80-099f-412a-80c1-422d320fb3d0) + +![Screenshot of MDX VS Code extension with `example.mdx` file open, showing mouse hovering over the red-underlined "nam" in "props.nam", with the IntelliSense hover card showing the error "Property 'nam' does not exist ..."](https://github.com/mdx-js/mdx/assets/1935696/ceb5612d-fb36-47b0-8ef5-415e1fa32684) + +![Screenshot of MDX VS Code extension with `example.tsx` file open, showing mouse hovering over the red-underlined "Example" in "", with the IntelliSense hover card showing the error "Property 'name' is missing ..."](https://github.com/mdx-js/mdx/assets/1935696/d510f1c8-6fe4-4527-8f6f-bd46bd737077) + ### Components There is one special prop: `components`. From c86da5974657fbccba9c084ecdcdf1f7cca66114 Mon Sep 17 00:00:00 2001 From: Karl Horky Date: Mon, 8 Jul 2024 13:14:34 +0200 Subject: [PATCH 2/7] Fix linting warnings Signed-off-by: Karl Horky --- docs/docs/using-mdx.mdx | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/docs/docs/using-mdx.mdx b/docs/docs/using-mdx.mdx index b29e23cbd..a99e823eb 100644 --- a/docs/docs/using-mdx.mdx +++ b/docs/docs/using-mdx.mdx @@ -219,13 +219,15 @@ To declare a type for the `props` object, use the JSDoc `@typedef` tag: # Hello {props.name} ``` -This will be used by [the MDX VS Code extension](https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx) to show JSDoc information and errors in IntelliSense hovers (see the [MDX Analyzer Props docs](https://github.com/mdx-js/mdx-analyzer#props) for more details): +This will be used by [the MDX VS Code extension][mdx-vscode-extension] to show +JSDoc information and errors in IntelliSense hovers (see the +[MDX Analyzer Props docs][mdx-analyzer-props-docs] for more details): -![Screenshot of MDX VS Code extension with `example.mdx` file open, showing mouse hovering over "name" in "props.name", with the IntelliSense hover card showing the details from the JSDoc type](https://github.com/mdx-js/mdx/assets/1935696/de2cdc80-099f-412a-80c1-422d320fb3d0) +![Screenshot of MDX VS Code extension with `example.mdx` file open, showing mouse hovering over ”name“ in ”props.name“, with the IntelliSense hover card showing the details from the JSDoc type](https://github.com/mdx-js/mdx/assets/1935696/de2cdc80-099f-412a-80c1-422d320fb3d0) -![Screenshot of MDX VS Code extension with `example.mdx` file open, showing mouse hovering over the red-underlined "nam" in "props.nam", with the IntelliSense hover card showing the error "Property 'nam' does not exist ..."](https://github.com/mdx-js/mdx/assets/1935696/ceb5612d-fb36-47b0-8ef5-415e1fa32684) +![Screenshot of MDX VS Code extension with `example.mdx` file open, showing mouse hovering over the red-underlined ”nam“ in ”props.nam“, with the IntelliSense hover card showing the error ”Property ‘nam’ does not exist ...“](https://github.com/mdx-js/mdx/assets/1935696/ceb5612d-fb36-47b0-8ef5-415e1fa32684) -![Screenshot of MDX VS Code extension with `example.tsx` file open, showing mouse hovering over the red-underlined "Example" in "", with the IntelliSense hover card showing the error "Property 'name' is missing ..."](https://github.com/mdx-js/mdx/assets/1935696/d510f1c8-6fe4-4527-8f6f-bd46bd737077) +![Screenshot of MDX VS Code extension with `example.tsx` file open, showing mouse hovering over the red-underlined ”Example“ in ”“, with the IntelliSense hover card showing the error ”Property ‘name’ is missing ...“](https://github.com/mdx-js/mdx/assets/1935696/d510f1c8-6fe4-4527-8f6f-bd46bd737077) ### Components @@ -555,10 +557,14 @@ providers: pass components explicitly. [what]: /docs/what-is-mdx/ +[mdx-analyzer-props-docs]: https://github.com/mdx-js/mdx-analyzer#props + [mdx-react]: /packages/react/ [mdx-preact]: /packages/preact/ +[mdx-vscode-extension]: https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx + [mdx-vue]: /packages/vue/ [processor-options]: /packages/mdx/#processoroptions From 83033158b77d319ab6908974d046c8146d3490d0 Mon Sep 17 00:00:00 2001 From: Karl Horky Date: Mon, 8 Jul 2024 13:18:52 +0200 Subject: [PATCH 3/7] Fix quotes? Signed-off-by: Karl Horky --- docs/docs/using-mdx.mdx | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/docs/using-mdx.mdx b/docs/docs/using-mdx.mdx index a99e823eb..aa1a2c35a 100644 --- a/docs/docs/using-mdx.mdx +++ b/docs/docs/using-mdx.mdx @@ -223,11 +223,11 @@ This will be used by [the MDX VS Code extension][mdx-vscode-extension] to show JSDoc information and errors in IntelliSense hovers (see the [MDX Analyzer Props docs][mdx-analyzer-props-docs] for more details): -![Screenshot of MDX VS Code extension with `example.mdx` file open, showing mouse hovering over ”name“ in ”props.name“, with the IntelliSense hover card showing the details from the JSDoc type](https://github.com/mdx-js/mdx/assets/1935696/de2cdc80-099f-412a-80c1-422d320fb3d0) +![Screenshot of MDX VS Code extension with `example.mdx` file open, showing mouse hovering over “name” in “props.name”, with the IntelliSense hover card showing the details from the JSDoc type](https://github.com/mdx-js/mdx/assets/1935696/de2cdc80-099f-412a-80c1-422d320fb3d0) -![Screenshot of MDX VS Code extension with `example.mdx` file open, showing mouse hovering over the red-underlined ”nam“ in ”props.nam“, with the IntelliSense hover card showing the error ”Property ‘nam’ does not exist ...“](https://github.com/mdx-js/mdx/assets/1935696/ceb5612d-fb36-47b0-8ef5-415e1fa32684) +![Screenshot of MDX VS Code extension with `example.mdx` file open, showing mouse hovering over the red-underlined “nam” in “props.nam”, with the IntelliSense hover card showing the error “Property ‘nam’ does not exist ...”](https://github.com/mdx-js/mdx/assets/1935696/ceb5612d-fb36-47b0-8ef5-415e1fa32684) -![Screenshot of MDX VS Code extension with `example.tsx` file open, showing mouse hovering over the red-underlined ”Example“ in ”“, with the IntelliSense hover card showing the error ”Property ‘name’ is missing ...“](https://github.com/mdx-js/mdx/assets/1935696/d510f1c8-6fe4-4527-8f6f-bd46bd737077) +![Screenshot of MDX VS Code extension with `example.tsx` file open, showing mouse hovering over the red-underlined “Example” in “”, with the IntelliSense hover card showing the error “Property ‘name’ is missing ...”](https://github.com/mdx-js/mdx/assets/1935696/d510f1c8-6fe4-4527-8f6f-bd46bd737077) ### Components From 59f4eb610790e1141610637f0d249bb24ba9da52 Mon Sep 17 00:00:00 2001 From: Karl Horky Date: Mon, 8 Jul 2024 16:08:42 +0200 Subject: [PATCH 4/7] Switch to s instead Signed-off-by: Karl Horky --- docs/docs/using-mdx.mdx | 37 ++++++++++++++----------------------- 1 file changed, 14 insertions(+), 23 deletions(-) diff --git a/docs/docs/using-mdx.mdx b/docs/docs/using-mdx.mdx index aa1a2c35a..3217208e1 100644 --- a/docs/docs/using-mdx.mdx +++ b/docs/docs/using-mdx.mdx @@ -206,28 +206,12 @@ console.log(React.createElement(Example, {name: 'Venus', year: 2021})) console.log() ``` -#### TypeScript: `Props` Type - -To declare a type for the `props` object, use the JSDoc `@typedef` tag: - -```mdx -{/** - * @typedef Props - * @property {string} name - * Who to greet. */} - -# Hello {props.name} -``` - -This will be used by [the MDX VS Code extension][mdx-vscode-extension] to show -JSDoc information and errors in IntelliSense hovers (see the -[MDX Analyzer Props docs][mdx-analyzer-props-docs] for more details): - -![Screenshot of MDX VS Code extension with `example.mdx` file open, showing mouse hovering over “name” in “props.name”, with the IntelliSense hover card showing the details from the JSDoc type](https://github.com/mdx-js/mdx/assets/1935696/de2cdc80-099f-412a-80c1-422d320fb3d0) - -![Screenshot of MDX VS Code extension with `example.mdx` file open, showing mouse hovering over the red-underlined “nam” in “props.nam”, with the IntelliSense hover card showing the error “Property ‘nam’ does not exist ...”](https://github.com/mdx-js/mdx/assets/1935696/ceb5612d-fb36-47b0-8ef5-415e1fa32684) - -![Screenshot of MDX VS Code extension with `example.tsx` file open, showing mouse hovering over the red-underlined “Example” in “”, with the IntelliSense hover card showing the error “Property ‘name’ is missing ...”](https://github.com/mdx-js/mdx/assets/1935696/d510f1c8-6fe4-4527-8f6f-bd46bd737077) + + **Note**: + Users of [the MDX VS Code extension][mdx-vscode-extension] can add type + checking of `props` with a JSDoc comment. + See [`mdx-js/mdx-analyzer`][mdx-analyzer] for more info. + ### Components @@ -348,6 +332,13 @@ as follows: * Otherwise, if it starts with a lowercase, it’s a literal (`` -> `h('a')`) * Otherwise, it’s an identifier (`` -> `h(A)`), which means a component `A` + + **Note**: + Users of [the MDX VS Code extension][mdx-vscode-extension] can add type + checking of provided and passed components with a JSDoc comment. + See [`mdx-js/mdx-analyzer`][mdx-analyzer] for more info. + + ### Layout There is one special component: the layout. @@ -557,7 +548,7 @@ providers: pass components explicitly. [what]: /docs/what-is-mdx/ -[mdx-analyzer-props-docs]: https://github.com/mdx-js/mdx-analyzer#props +[mdx-analyzer]: https://github.com/mdx-js/mdx-analyzer [mdx-react]: /packages/react/ From 192b11debd7d7bd75d174a2a9c3781256f1d9fb6 Mon Sep 17 00:00:00 2001 From: Karl Horky Date: Mon, 8 Jul 2024 16:11:46 +0200 Subject: [PATCH 5/7] Import Note Signed-off-by: Karl Horky --- docs/docs/using-mdx.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/docs/using-mdx.mdx b/docs/docs/using-mdx.mdx index 3217208e1..2fc0a12ab 100644 --- a/docs/docs/using-mdx.mdx +++ b/docs/docs/using-mdx.mdx @@ -1,3 +1,5 @@ +import {Note} from '../_component/note.jsx' + export const info = { author: [ {github: 'wooorm', name: 'Titus Wormer', twitter: 'wooorm'} From 46c4528f96e8430b682c8975c40d53aa4b3e1172 Mon Sep 17 00:00:00 2001 From: Karl Horky Date: Wed, 10 Jul 2024 19:21:23 +0200 Subject: [PATCH 6/7] Remove link Signed-off-by: Karl Horky --- docs/docs/using-mdx.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/using-mdx.mdx b/docs/docs/using-mdx.mdx index 2fc0a12ab..0693499ef 100644 --- a/docs/docs/using-mdx.mdx +++ b/docs/docs/using-mdx.mdx @@ -210,7 +210,7 @@ console.log() **Note**: - Users of [the MDX VS Code extension][mdx-vscode-extension] can add type + Users of the MDX VS Code extension can add type checking of `props` with a JSDoc comment. See [`mdx-js/mdx-analyzer`][mdx-analyzer] for more info. @@ -336,7 +336,7 @@ as follows: **Note**: - Users of [the MDX VS Code extension][mdx-vscode-extension] can add type + 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. From 8ea0ff7b37f56d5e91e1014fd282efb2c3b78147 Mon Sep 17 00:00:00 2001 From: Karl Horky Date: Wed, 10 Jul 2024 19:25:11 +0200 Subject: [PATCH 7/7] Remove unused link Signed-off-by: Karl Horky --- docs/docs/using-mdx.mdx | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/docs/using-mdx.mdx b/docs/docs/using-mdx.mdx index 0693499ef..de7976c82 100644 --- a/docs/docs/using-mdx.mdx +++ b/docs/docs/using-mdx.mdx @@ -556,8 +556,6 @@ providers: pass components explicitly. [mdx-preact]: /packages/preact/ -[mdx-vscode-extension]: https://marketplace.visualstudio.com/items?itemName=unifiedjs.vscode-mdx - [mdx-vue]: /packages/vue/ [processor-options]: /packages/mdx/#processoroptions