{children}
19 | {children}
15 | }
16 |
--------------------------------------------------------------------------------
/packages/loader/index.cjs:
--------------------------------------------------------------------------------
1 | 'use strict'
2 |
3 | /**
4 | * Webpack loader
5 | *
6 | * @todo once webpack supports ESM loaders, remove this wrapper.
7 | *
8 | * @param {string} code
9 | */
10 | module.exports = function (code) {
11 | const callback = this.async()
12 | // Note that `import()` caches, so this should be fast enough.
13 | import('./lib/index.js').then((module) =>
14 | module.loader.call(this, code, callback)
15 | )
16 | }
17 |
--------------------------------------------------------------------------------
/website/schema-description.js:
--------------------------------------------------------------------------------
1 | export const schema = {
2 | strip: ['script', 'style'],
3 | ancestors: {},
4 | protocols: {href: ['http', 'https']},
5 | tagNames: [
6 | 'ul',
7 | 'ol',
8 | 'li',
9 | 'pre',
10 | 'code',
11 | 'strong',
12 | 'p',
13 | 'b',
14 | 'em',
15 | 'i',
16 | 'strike',
17 | 's',
18 | 'del',
19 | 'a'
20 | ],
21 | attributes: {
22 | a: ['href'],
23 | '*': []
24 | }
25 | }
26 |
--------------------------------------------------------------------------------
/packages/esbuild/test/files/components.js:
--------------------------------------------------------------------------------
1 | import React from 'react'
2 |
3 | /**
4 | * @param {Record
8 | {data.map((d, i) => (
9 |
18 | ))}
19 |
20 | )
21 | }
22 |
--------------------------------------------------------------------------------
/renovate.json5:
--------------------------------------------------------------------------------
1 | {
2 | extends: ['config:base', ':preserveSemverRanges'],
3 | schedule: 'before 3am on Monday',
4 | packageRules: [
5 | {
6 | matchPackageNames: [
7 | // `react`/`react-dom`/`react-server-dom-webpack` latest don’t support
8 | // RSC.
9 | 'react',
10 | 'react-dom',
11 | 'react-fetch',
12 | 'react-server-dom-webpack',
13 | // `node-loader@2` depends on Node 16+. Our website is on Vercel/AWS which don’t support Node 16.
14 | '@node-loader/babel',
15 | '@node-loader/core'
16 | ],
17 | enabled: false
18 | }
19 | ]
20 | }
21 |
--------------------------------------------------------------------------------
/docs/404.server.mdx:
--------------------------------------------------------------------------------
1 | import {Note} from './_component/note.server.js'
2 | export {Home as default} from './_component/home.server.js'
3 | export const navExclude = true
4 |
5 | # 404: Not found
6 |
7 | Aww, snap.
8 | Unfortunately this page doesn’t exist.
9 | Perhaps you can find what you’re looking for [on GitHub][search]?
10 |
11 |
10 |
12 | {props.meta.schemaOrg && (
13 |
16 | )}
17 |
18 |
20 |
22 |
24 | )
25 | }
26 |
--------------------------------------------------------------------------------
/docs/docs/index.server.mdx:
--------------------------------------------------------------------------------
1 | import {NavGroup} from '../_component/nav.server.js'
2 | export const navSortSelf = 1
3 | export const info = {
4 | author: [{name: 'MDX Contributors'}],
5 | published: new Date('2021-11-01'),
6 | modified: new Date('2021-11-01')
7 | }
8 |
9 | # Docs
10 |
11 | These docs explain the core concepts of MDX.
12 | How the format works, how to add it to your site, how to use MDX files, and how
13 | to extend them.
14 | Reading through these should give you a good understanding of MDX.
15 |
16 | {
17 | (() => {
18 | const category = props.navTree.children.find(
19 | item => item.name === '/docs/'
20 | )
21 |
22 | return (
23 |
26 | )
27 | })()
28 | }
29 |
--------------------------------------------------------------------------------
/packages/vue/lib/index.js:
--------------------------------------------------------------------------------
1 | /**
2 | * @typedef {import('mdx/types').MDXComponents} Components
3 | */
4 |
5 | import {provide, inject, createVNode, Fragment} from 'vue'
6 |
7 | /** @type {import('vue').Component<{components?: Components}>} */
8 | export const MDXProvider = {
9 | name: 'MDXProvider',
10 | props: {components: {type: Object, default: () => ({})}},
11 | setup(props) {
12 | provide('$mdxComponents', props.components)
13 | },
14 | /**
15 | * @this {import('vue').ComponentPublicInstance}
16 | */
17 | render() {
18 | return createVNode(
19 | Fragment,
20 | null,
21 | this.$slots.default ? this.$slots.default() : []
22 | )
23 | }
24 | }
25 |
26 | /** @returns {Components} */
27 | export function useMDXComponents() {
28 | return inject('$mdxComponents', {})
29 | }
30 |
--------------------------------------------------------------------------------
/packages/mdx/lib/run.js:
--------------------------------------------------------------------------------
1 | /** @type {new (code: string, ...args: ArrayHello, World!
', 30 | 'should compile' 31 | ) 32 | 33 | await fs.unlink(path.join(base, 'register.mdx')) 34 | }) 35 | 36 | test.run() 37 | -------------------------------------------------------------------------------- /docs/playground.server.mdx: -------------------------------------------------------------------------------- 1 | import {Note} from './_component/note.server.js' 2 | import {Editor} from './_component/editor.client.js' 3 | export const navSortSelf = 5 4 | export const info = { 5 | author: [ 6 | {name: 'John Otander', github: 'johno', twitter: '4lpine'}, 7 | {name: 'Titus Wormer', github: 'wooorm', twitter: 'wooorm'} 8 | ], 9 | published: new Date('2021-09-13'), 10 | modified: new Date('2021-11-01') 11 | } 12 | export const playgroundSource = `Hello, world! 13 | Below is an example of markdown in JSX. 14 | 15 |
16 | Try and change the background color to \`tomato\`.
17 |
`
18 |
19 | # Playground
20 |
21 | Here you can play with the MDX format.
22 | Write some MDX to find out what it turns into. {/* more */}
23 | You can see the rendered result, the generated code, and the intermediary
24 | ASTs.
25 | This can be helpful for debugging or exploring.
26 | To read about how the MDX format works, we recommend that you start with
27 | [§ What is MDX][what].
28 |
29 | Hello, World!
', 37 | 'should compile' 38 | ) 39 | 40 | await fs.unlink(new URL('esm-loader.mdx', import.meta.url)) 41 | }) 42 | 43 | test.run() 44 | -------------------------------------------------------------------------------- /packages/remark-mdx/index.js: -------------------------------------------------------------------------------- 1 | /** 2 | * @typedef {import('mdast').Root} Root 3 | * @typedef {import('micromark-extension-mdxjs').Options} MicromarkOptions 4 | * @typedef {import('mdast-util-mdx').ToMarkdownOptions} ToMarkdownOptions 5 | * @typedef {MicromarkOptions & ToMarkdownOptions} Options 6 | * 7 | * @typedef {import('mdast-util-mdx')} DoNotTouchAsThisImportItIncludesMdxInTree 8 | */ 9 | 10 | import {mdxjs} from 'micromark-extension-mdxjs' 11 | import {mdxFromMarkdown, mdxToMarkdown} from 'mdast-util-mdx' 12 | 13 | /** 14 | * Plugin to support MDX (import/exports: `export {x} from 'y'`; expressions: 15 | * `{1 + 1}`; and JSX: ``). 16 | * 17 | * @type {import('unified').Plugin<[Options?]|ArrayHello, World!
', 44 | 'should compile' 45 | ) 46 | 47 | await fs.unlink(new URL('rollup.mdx', import.meta.url)) 48 | await fs.unlink(new URL('rollup.js', import.meta.url)) 49 | }) 50 | 51 | test.run() 52 | -------------------------------------------------------------------------------- /docs/_component/nav-site.server.js: -------------------------------------------------------------------------------- 1 | import React from 'react' 2 | import {config} from '../_config.js' 3 | import {NavGroup} from './nav.server.js' 4 | import {Mdx} from './icon/mdx.server.js' 5 | import {GitHub} from './icon/github.server.js' 6 | import {Twitter} from './icon/twitter.server.js' 7 | import {OpenCollective} from './icon/open-collective.server.js' 8 | 9 | export function NavSiteSkip() { 10 | return ( 11 | 16 | Skip to navigation 17 | 18 | ) 19 | } 20 | 21 | export function NavSite(props) { 22 | const {name, navTree} = props 23 | 24 | return ( 25 | 63 | ) 64 | } 65 | -------------------------------------------------------------------------------- /packages/register/package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "@mdx-js/register", 3 | "version": "2.1.5", 4 | "description": "Node hook to require MDX", 5 | "license": "MIT", 6 | "keywords": [ 7 | "mdx", 8 | "markdown", 9 | "jsx", 10 | "node", 11 | "require", 12 | "remark", 13 | "react" 14 | ], 15 | "homepage": "https://mdxjs.com", 16 | "repository": { 17 | "type": "git", 18 | "url": "https://github.com/mdx-js/mdx", 19 | "directory": "packages/register" 20 | }, 21 | "bugs": "https://github.com/mdx-js/mdx/issues", 22 | "funding": { 23 | "type": "opencollective", 24 | "url": "https://opencollective.com/unified" 25 | }, 26 | "author": "Titus Wormer-
13 | {sortItems(items, sort).map((d) => (
14 |
45 |
47 | )
48 | }
49 | }
50 | }
51 |
52 | if (includePublished && (matter.published || meta.published)) {
53 | published = dateTimeFormat.format(matter.published || meta.published)
54 | }
55 |
56 | return (
57 | {description}
46 |x
` but also 14 | * `heading
`. 17 | * 18 | * @type {import('unified').Plugin
34 |
72 | )
73 | }
74 |
75 | export function BlogGroup(props) {
76 | const {items, className, sort = 'navSortSelf,meta.title', ...rest} = props
77 | const sorted = sortItems(items, sort)
78 |
79 | return (
80 | <>
81 | {sorted.map((d) => (
82 | 35 | {title || defaultTitle} 36 |
37 |
38 | {meta.descriptionHast ? (
39 | toH(createElement, meta.descriptionHast)
40 | ) : description ? (
41 |
47 | {description}
42 | ) : null} 43 | 44 | Continue reading » 45 | 46 |
51 |
71 |
52 | {meta.author ? (
53 | <>
54 | By {meta.author}
55 |
56 | 57 | ) : undefined} 58 | Reading time: {timeLabel} 59 |
60 | {meta.published ? (
61 | 56 | 57 | ) : undefined} 58 | Reading time: {timeLabel} 59 |
62 |
63 | Published on{' '}
64 |
67 |
68 |
69 | ) : undefined}
70 | Hello, world!
58 | ``` 59 | 60 | [See the blog post for further reading](/blog/custom-pragma/) 61 | 62 | ## MDXProvider 63 | 64 | This shouldn’t affect most usecases, however if you’re nesting component 65 | contexts and rely on them not being merged you will have to use the functional 66 | form which allows you to customize the merge. 67 | By ignoring outer context components and returning a new component mapping, you 68 | will restore the old behavior: 69 | 70 | ```js 71 |
50 |
67 |
68 | Expand equivalent JSX
51 | 52 | ```jsx path="output.jsx" 53 | <> 54 |55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 |
64 | 65 | ``` 66 |
66 |
85 |
86 |
94 |
104 |
114 |
115 | ```
116 |
117 |
118 | [commonmark]: https://spec.commonmark.org/current/
119 |
120 | [gfm]: https://github.github.com/gfm/
121 |
122 | [remark-gfm]: https://github.com/remarkjs/remark-gfm
123 |
124 | [options-remark-plugins]: /packages/mdx/#optionsremarkplugins
125 |
126 | [extend]: /docs/extending-mdx/
127 |
--------------------------------------------------------------------------------
/docs/guides/embed.server.mdx:
--------------------------------------------------------------------------------
1 | export const navSortSelf = 5
2 | export const info = {
3 | author: [
4 | {name: 'Titus Wormer', github: 'wooorm', twitter: 'wooorm'}
5 | ],
6 | published: new Date('2021-10-06'),
7 | modified: new Date('2022-06-17')
8 | }
9 |
10 | # Embed
11 |
12 | This guide explores how to embed things like tweets, gists or codepens in
13 | markdown. {/* more */}
14 | MDX supports standard markdown syntax ([CommonMark][]).
15 | It does not support embeds by default.
16 |
17 | There are two ways to accomplish embeds: at compile time or at runtime.
18 | Doing it at compile time means the effort is spent upfront so that readers will
19 | have a fast experience as no requests have to be made on the client.
20 | Doing it at runtime gives more flexibility by moving the work to the client.
21 | This can result in a slow experience for readers though.
22 | It also depends on what framework you use (as in it’s specific to React, Preact,
23 | Vue, etc.)
24 |
25 | ## Embeds at compile time
26 |
27 | You can use [`@remark-embedder/core`][remark-embedder] by doing something like
28 | this:
29 |
30 | ```js path="example.js"
31 | import {compile} from '@mdx-js/mdx'
32 | // Node currently can’t pick up on the default exports by `@remark-embedder`.
33 | import fauxRemarkEmbedder from '@remark-embedder/core'
34 | import fauxOembedTransformer from '@remark-embedder/transformer-oembed'
35 | const remarkEmbedder = fauxRemarkEmbedder.default
36 | const oembedTransformer = fauxOembedTransformer.default
37 |
38 | const code = `
39 | Check out this video:
40 |
41 | https://www.youtube.com/watch?v=dQw4w9WgXcQ
42 | `
43 |
44 | console.log(
45 | String(
46 | await compile(code, {
47 | remarkPlugins: [[remarkEmbedder, {transformers: [oembedTransformer]}]]
48 | })
49 | )
50 | )
51 | ```
52 |
53 | Expand equivalent JSX
67 | 68 | ```jsx path="output.jsx" 69 | <> 70 |GFM
71 |Autolink literals
72 |73 | www.example.com, 74 | https://example.com, and 75 | contact@example.com. 76 |
77 |Footnote
78 |A note1
79 |Strikethrough
80 |
81 | one or two tildes.
82 |
Table
84 || a | 88 |b | 89 |c | 90 |d | 91 |
|---|
Tasklist
95 |-
96 |
- 97 | to do 98 | 99 |
- 100 | done 101 | 102 |
Footnotes
105 |-
106 |
-
107 |
108 | Big note. 109 | ↩ 110 |
111 |
112 |
54 |
63 |
64 | ## Embeds at run time
65 |
66 | You can use the React-specific [MDX Embed][mdx-embed] to embed things in MDX.
67 | Here is an example MDX file that uses a specific embed without `@mdx-js/react`:
68 |
69 | ```mdx path="example.mdx"
70 | import {CodePen} from 'mdx-embed'
71 |
72 | Here’s a codepen, and some other blog post text.
73 |
74 | Expand equivalent JSX
55 | 56 | ```jsx path="output.jsx" 57 | <> 58 |Check out this video:
59 | 60 | 61 | ``` 62 |
78 |
87 |
88 | If you don’t want to use explicit imports in MDX files:
89 |
90 | ```mdx path="example.mdx"
91 | Here’s a codepen, and some other blog post text.
92 |
93 | Expand equivalent JSX
79 | 80 | ```js path="output.jsx" 81 | <> 82 |Here’s a codepen, and some other blog post text.
83 |Online • Free 22 | 23 | ## Watch 24 | 25 | The conference is now over, but you can still watch the recordings! 26 | 27 | [Watch the talks →](https://egghead.io/playlists/mdx-conf-3fc2) 28 | 29 | ## About 30 | 31 | Join us for the first MDX conference! 32 | We’ll stream it directly to you, for free. 33 | 34 | MDX has grown rapidly since the [first commit][] two and a half years ago. 35 | We’d like to celebrate our accomplishments so far, and talk about what lies 36 | ahead. 37 | We’ve got lots of plans. 38 | 39 | Learn how MDX increases developer productivity, improves educational 40 | content authoring, and even peek behind the curtains to see how MDX works. 41 | 42 | ## Speakers 43 | 44 | ### [Chris Biscardi](https://twitter.com/chrisbiscardi) 45 | 46 | [](https://twitter.com/chrisbiscardi) 47 | 48 | Keynote: The past, present, and future of MDX 49 | 50 | ### [Monica Powell](https://twitter.com/waterproofheart) 51 | 52 | [](https://twitter.com/waterproofheart) 53 | 54 | Migrating to MDX 55 | 56 | ### [Laurie Barth](https://twitter.com/laurieontech) 57 | 58 | [](https://twitter.com/laurieontech) 59 | 60 | MDX v2 syntax 61 | 62 | ### [Cole Bemis](https://twitter.com/colebemis) 63 | 64 | [](https://twitter.com/colebemis) 65 | 66 | Demystifying MDX 67 | 68 | ### [Prince Wilson](https://twitter.com/maxcell) 69 | 70 | [](https://twitter.com/maxcell) 71 | 72 | Personal site playgrounds 73 | 74 | ### [Kathleen McMahon](https://twitter.com/resource11) 75 | 76 | [](https://twitter.com/resource11) 77 | 78 | Digital gardening with MDX magic 79 | 80 | ### [Rodrigo Pombo](https://twitter.com/pomber) 81 | 82 | [](https://twitter.com/pomber) 83 | 84 | The X in MDX 85 | 86 | ### [Jonathan Bakebwa](https://twitter.com/codebender828) 87 | 88 | [](https://twitter.com/codebender828) 89 | 90 | MDX and Vue/Nuxt 91 | 92 | ## Sign up 93 | 94 |
hi
') 57 | }) 58 | 59 | test('should evaluate some more complex MDX code (text, inline)', async () => { 60 | const {default: Content} = await evaluate( 61 | '*a* **b** `c` MDX' 62 | ) 63 | 64 | assert.equal( 65 | await vueToString(Content), 66 | 'a b c MDX
hi
' 84 | ) 85 | }) 86 | 87 | test('should support passing `components`', async () => { 88 | const {default: Content} = await evaluate('# hi') 89 | 90 | assert.equal( 91 | await vueToString(Content, {components: {h1: 'h2'}}), 92 | 'hi
' 93 | ) 94 | }) 95 | 96 | test('should support `MDXProvider`', async () => { 97 | const {default: Content} = await evaluate('# hi') 98 | 99 | assert.equal( 100 | await vueToString({ 101 | data() { 102 | return {components: {h1: 'h2'}} 103 | }, 104 | template: 105 | 'hi
' 109 | ) 110 | }) 111 | 112 | test('should support the MDX provider w/o components', async () => { 113 | const {default: Content} = await evaluate('# hi') 114 | 115 | assert.equal( 116 | await vueToString({ 117 | template: 'hi
' 121 | ) 122 | }) 123 | 124 | test('should support the MDX provider w/o content', async () => { 125 | assert.equal( 126 | await vueToString({ 127 | template: 'hi
' 26 | ) 27 | }) 28 | 29 | test('should support `wrapper` in `components`', async () => { 30 | const {default: Content} = await evaluate('# hi', { 31 | ...runtime, 32 | useMDXComponents 33 | }) 34 | 35 | assert.equal( 36 | renderToString( 37 |hi
hi
\nhello
' 73 | ) 74 | }) 75 | 76 | test('should support components as a function', async () => { 77 | const {default: Content} = await evaluate('# hi\n## hello', { 78 | ...runtime, 79 | useMDXComponents 80 | }) 81 | 82 | assert.equal( 83 | renderToString( 84 |hi
\nhello
' 100 | ) 101 | }) 102 | 103 | test('should support a `disableParentContext` prop (sandbox)', async () => { 104 | const {default: Content} = await evaluate('# hi', { 105 | ...runtime, 106 | useMDXComponents 107 | }) 108 | 109 | assert.equal( 110 | renderToString( 111 |hi
' 122 | ) 123 | }) 124 | 125 | test('should support `withComponents`', async () => { 126 | const {default: Content} = await evaluate('# hi\n## hello', { 127 | ...runtime, 128 | useMDXComponents 129 | }) 130 | const With = withMDXComponents((props) => props.children) 131 | 132 | // Bug: this should use the `h2` component too, logically? 133 | // As `withMDXComponents` is deprecated, and it would probably be a breaking 134 | // change, we can just remove it later. 135 | assert.equal( 136 | renderToString( 137 |hi
\nhello
' 152 | ) 153 | }) 154 | 155 | test.run() 156 | -------------------------------------------------------------------------------- /packages/preact/test/test.jsx: -------------------------------------------------------------------------------- 1 | /* @jsx h */ 2 | /* @jsxFrag Fragment */ 3 | import {test} from 'uvu' 4 | import * as assert from 'uvu/assert' 5 | import {h} from 'preact' 6 | import * as runtime from 'preact/jsx-runtime' 7 | import {render} from 'preact-render-to-string' 8 | import {evaluate} from '@mdx-js/mdx' 9 | import {MDXProvider, useMDXComponents, withMDXComponents} from '../index.js' 10 | 11 | test('should support `components` with `MDXProvider`', async () => { 12 | const {default: Content} = await evaluate('# hi', { 13 | ...runtime, 14 | useMDXComponents 15 | }) 16 | 17 | assert.equal( 18 | render( 19 |hi
' 28 | ) 29 | }) 30 | 31 | test('should support `wrapper` in `components`', async () => { 32 | const {default: Content} = await evaluate('# hi', { 33 | ...runtime, 34 | useMDXComponents 35 | }) 36 | 37 | assert.equal( 38 | render( 39 |hi
hi
\nhello
' 75 | ) 76 | }) 77 | 78 | test('should support components as a function', async () => { 79 | const {default: Content} = await evaluate('# hi\n## hello', { 80 | ...runtime, 81 | useMDXComponents 82 | }) 83 | 84 | assert.equal( 85 | render( 86 |hi
\nhello
' 102 | ) 103 | }) 104 | 105 | test('should support a `disableParentContext` prop (sandbox)', async () => { 106 | const {default: Content} = await evaluate('# hi', { 107 | ...runtime, 108 | useMDXComponents 109 | }) 110 | 111 | assert.equal( 112 | render( 113 |hi
' 124 | ) 125 | }) 126 | 127 | test('should support `withComponents`', async () => { 128 | const {default: Content} = await evaluate('# hi\n## hello', { 129 | ...runtime, 130 | useMDXComponents 131 | }) 132 | const With = withMDXComponents((props) => props.children) 133 | 134 | // Bug: this should use the `h2` component too, logically? 135 | // As `withMDXComponents` is deprecated, and it would probably be a breaking 136 | // change, we can just remove it later. 137 | assert.equal( 138 | render( 139 |hi
\nhello
' 154 | ) 155 | }) 156 | 157 | test.run() 158 | -------------------------------------------------------------------------------- /packages/mdx/lib/core.js: -------------------------------------------------------------------------------- 1 | /** 2 | * @typedef {import('unified').Processor} Processor 3 | * @typedef {import('unified').PluggableList} PluggableList 4 | * @typedef {import('./plugin/recma-document.js').RecmaDocumentOptions} RecmaDocumentOptions 5 | * @typedef {import('./plugin/recma-stringify.js').RecmaStringifyOptions} RecmaStringifyOptions 6 | * @typedef {import('./plugin/recma-jsx-rewrite.js').RecmaJsxRewriteOptions} RecmaJsxRewriteOptions 7 | * @typedef {import('remark-rehype').Options} RemarkRehypeOptions 8 | * 9 | * @typedef BaseProcessorOptions 10 | * @property {boolean} [jsx=false] 11 | * Whether to keep JSX. 12 | * @property {'mdx'|'md'} [format='mdx'] 13 | * Format of the files to be processed. 14 | * @property {'program'|'function-body'} [outputFormat='program'] 15 | * Whether to compile to a whole program or a function body.. 16 | * @property {Array|
28 | Vercel 29 | 
30 | |
31 |
32 | Motif 33 | 
34 | |
35 |
36 | HashiCorp 37 | 
38 | |
39 |
40 | GitBook 41 | 
42 | |
43 |
44 | Gatsby 45 | 
46 | |
47 | |||||
|
51 | Netlify 52 | {/* OC has a sharper image */} 53 | 
54 | |
55 |
56 | Coinbase 57 | 
58 | |
59 |
60 | ThemeIsle 61 | 
62 | |
63 |
64 | Expo 65 | 
66 | |
67 |
68 | Boost Note 69 | 
70 | |
71 |
72 | Holloway 73 | 
74 | |
75 | 76 | | 77 | | 78 | | |
|
81 | 82 | You? 83 | 84 | |
85 | |||||||||
Hello, World!
93 | ``` 94 | 95 | ## API 96 | 97 | > 🪦 **Legacy**: This package is not recommended for use as it depends on 98 | > deprecated Node features. 99 | 100 | This package does not export anything. 101 | It changes Node’s internals. 102 | 103 | To pass options, you can make your own hook, such as this `my-hook.cjs`: 104 | 105 | ```js 106 | 'use strict' 107 | 108 | const register = require('@mdx-js/register/lib/index.cjs') 109 | 110 | register({/* Options… */}) 111 | ``` 112 | 113 | Which can then be used with `node -r ./my-hook.cjs`. 114 | 115 | The register hook uses 116 | [`evaluateSync`][eval-sync]. 117 | That means `import` (and `export … from`) are not supported when requiring 118 | `.mdx` files. 119 | 120 | ## Types 121 | 122 | This package is not typed as [TypeScript][] seems to not support `.cjs` files 123 | yet. 124 | 125 | ## Security 126 | 127 | See [§ Security][security] on our website for information. 128 | 129 | ## Contribute 130 | 131 | See [§ Contribute][contribute] on our website for ways to get started. 132 | See [§ Support][support] for ways to get help. 133 | 134 | This project has a [code of conduct][coc]. 135 | By interacting with this repository, organization, or community you agree to 136 | abide by its terms. 137 | 138 | ## License 139 | 140 | [MIT][] © [Titus Wormer][author] 141 | 142 | [build-badge]: https://github.com/mdx-js/mdx/workflows/main/badge.svg 143 | 144 | [build]: https://github.com/mdx-js/mdx/actions 145 | 146 | [coverage-badge]: https://img.shields.io/codecov/c/github/mdx-js/mdx/main.svg 147 | 148 | [coverage]: https://codecov.io/github/mdx-js/mdx 149 | 150 | [downloads-badge]: https://img.shields.io/npm/dm/@mdx-js/register.svg 151 | 152 | [downloads]: https://www.npmjs.com/package/@mdx-js/register 153 | 154 | [sponsors-badge]: https://opencollective.com/unified/sponsors/badge.svg 155 | 156 | [backers-badge]: https://opencollective.com/unified/backers/badge.svg 157 | 158 | [collective]: https://opencollective.com/unified 159 | 160 | [chat-badge]: https://img.shields.io/badge/chat-discussions-success.svg 161 | 162 | [chat]: https://github.com/mdx-js/mdx/discussions 163 | 164 | [npm]: https://docs.npmjs.com/cli/install 165 | 166 | [yarn]: https://classic.yarnpkg.com/docs/cli/add/ 167 | 168 | [contribute]: https://mdxjs.com/community/contribute/ 169 | 170 | [support]: https://mdxjs.com/community/support/ 171 | 172 | [coc]: https://github.com/mdx-js/.github/blob/main/code-of-conduct.md 173 | 174 | [mit]: https://github.com/mdx-js/mdx/blob/main/packages/register/license 175 | 176 | [author]: https://wooorm.com 177 | 178 | [require-extensions]: https://nodejs.org/api/modules.html#modules_require_extensions 179 | 180 | [eval-sync]: https://mdxjs.com/packages/mdx/#evaluatesyncfile-options 181 | 182 | [esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c 183 | 184 | [security]: https://mdxjs.com/getting-started/#security 185 | 186 | [typescript]: https://www.typescriptlang.org 187 | -------------------------------------------------------------------------------- /docs/index.server.mdx: -------------------------------------------------------------------------------- 1 | import {Note} from './_component/note.server.js' 2 | import {Chart} from './_component/snowfall.server.js' 3 | export {Home as default} from './_component/home.server.js' 4 | export const info = { 5 | author: [ 6 | {name: 'John Otander', github: 'johno', twitter: '4lpine'} 7 | ], 8 | published: new Date('2017-12-23'), 9 | modified: new Date('2022-02-01'), 10 | schemaOrg: { 11 | "@context": "https://schema.org", 12 | "@type": "SoftwareApplication", 13 | "additionalType": "ComputerLanguage", 14 | "name": "MDX", 15 | "description": "an authorable format for writing JSX in markdown documents", 16 | "applicationCategory": "DeveloperApplication", 17 | "operatingSystem": "Windows, MacOS, Linux", 18 | "url": "https://mdxjs.com", 19 | "sameAs": [ 20 | "https://www.wikidata.org/wiki/Q95971592", 21 | "https://www.wikidata.org/wiki/Q27966906", 22 | "https://www.wikidata.org/wiki/Q95961071", 23 | "https://en.wikipedia.org/wiki/MDX_(markup_language)", 24 | "https://github.com/mdx-js/mdx" 25 | ], 26 | "offers": { 27 | "@type": "Offer", 28 | "price": "0.00", 29 | "priceCurrency": "USD" 30 | } 31 | } 32 | } 33 | export const year = 2018 34 | 35 | {/* lint disable heading-style */} 36 | 37 | Markdown for the\ 38 | **component era** 39 | ================= 40 | 41 | MDX allows you to use JSX in your markdown content. 42 | You can import components, such as interactive charts or alerts, and embed them 43 | within your content. 44 | This makes writing long-form content with components a blast. {/* more */} 45 | 🚀 46 | [Continue reading »][what] 47 | 48 |
49 | ## New: MDX 2!
50 |
51 | Version 2 of MDX was released after years of hard work, and has many
52 | improvements.
53 | Here are the highlights:
54 |
55 |
71 |
72 | ## What does MDX do?
73 |
74 |
56 | * 📝 **Improved syntax** makes it easier to use markdown in JSX
57 | * 🧑💻 **JavaScript expressions** turn `{2 * Math.PI}` into {2 * Math.PI}
58 | * 🔌 New **esbuild**, **Rollup**, and **Node.js** integrations
59 | * ⚛️ **Any JSX runtime**: React, Preact, Vue, Emotion, you name it, they’re
60 | all supported
61 | * 🌳 **Improved AST** exposes more info in greater detail
62 | * 🏃♀️ Compiles at least **25% faster**
63 | * 🚴 Generated code runs twice as fast (**100% faster**)
64 | * 🚄 Bundle size of `@mdx-js/mdx` is more than three times as small
65 | (**250% smaller**)
66 | * 🧵 …and much, so much more
67 |
68 |
69 | [Continue reading »][v2]
70 |
75 |
111 |
112 | We made an interactive playground where you can try MDX out and see what it
113 | turns into.
114 | [Play »][playground]
115 |
116 | ## Get started
117 |
118 | There are integrations for most bundlers, frameworks, and editors.
119 | Whether you build with Next.js, Docusaurus, or Gatsby.
120 | You prefer esbuild, Rollup, or webpack.
121 | You’re using React, Preact, or Vue.
122 | [Get started »][getting-started]
123 |
124 | ## MDX in short
125 |
126 |
76 | You write markdown with embedded components through JSX:
77 |
78 | ```mdx path="example.mdx"
79 | import {Chart} from './snowfall.js'
80 | export const year = 2018
81 |
82 | # Last year’s snowfall
83 |
84 | In {year}, the snowfall was above average.
85 | It was followed by a warm spring which caused
86 | flood conditions in many of the nearby rivers.
87 |
88 |
91 |
92 |
93 | It gets compiled to JavaScript that you can use in any framework that
94 | supports JSX:
95 |
96 | {/* lint disable */}
97 |
98 |
110 |
99 | # Last year’s snowfall
100 |
101 | In {year}, the snowfall was above average.
102 | It was followed by a warm spring which caused flood conditions in many of
103 | the nearby rivers.
104 |
105 |
107 |
108 | {/* lint enable */}
109 |
127 | * ❤️ **Powerful**: MDX blends markdown and JSX syntax to fit perfectly in
128 | JSX-based projects
129 | * 💻 **Everything is a component**: Use existing components in your
130 | MDX and import other MDX files as components
131 | * 🔧 **Customizable**: Decide which component is rendered for each markdown
132 | construct (`{h1: MyHeading}`)
133 | * 📚 **Markdown-based**: The simplicity and elegance of markdown remains,
134 | you use JSX only when you want to
135 | * 🔥 **Blazingly blazing fast**: MDX has no runtime, all compilation occurs
136 | during the build stage
137 |
138 |
139 | {/* To do: quotes. */}
140 |
141 | > It’s extremely useful for using design system components to render markdown
142 | > and weaving interactive components in with existing markdown.
143 | >
144 | > — [**@chrisbiscardi**][quote]
145 |
146 | [quote]: https://twitter.com/chrisbiscardi/status/1022304288326864896
147 |
148 | [what]: /docs/what-is-mdx/
149 |
150 | [v2]: /blog/v2/
151 |
152 | [playground]: /playground/
153 |
154 | [getting-started]: /docs/getting-started/
155 |
--------------------------------------------------------------------------------