mdx-js / mdx Goto Github PK

In certain cases it'd be nice to be able to render jsx components directly, the components to be rendered need to be provided in scope.

Proposed syntax:

[[jsx]]
| <MyComponent
|   with={some}
|   props={here}
| />

Another possible syntax:

Using code blocks with a ! postfix:

```.jsx!
<MyComponent
  with={some}
  props={here}
/>
\```

If you create a file like:

# heading

hello `test`

It'll parse single quoted lines as code blocks instead of inlineCode as defined in the spec. I'm not sure if this is an issue with remark or mdxast 🤔

Old:

<TerminalInput prefix>npm i next@latest react@latest react-dom@latest</TerminalInput>

<Caption>In addition to bumping Next.js etc...</Caption>

new:

<TerminalInput prefix>npm i next@latest react@latest react-dom@latest</TerminalInput>
<Caption>In addition to bumping Next.js etc...</Caption>

This will add a context that provides an element to component mapping, and any other globally available components.

As an example API, this will render Heading for the h1 element in readme.md.

import React from 'react'
import { MarkdownProvider } from '@compositor/markdown'

import { Heading } from './ui'

import Readme from './readme.md

export default () =>
  <MarkdownProvider components={{ h1: Heading }}>
    <Readme />
  </MarkdownProvider>

• loader
• mdx
• mdxast
• remark-images
• tag

This will be, at least temporarily, required for more complex blocks of jsx due to limitations in parsing.

In the renderer we should be adding a key prop, we currently aren't resulting in the following error:

Warning: Each child in an array or iterator should have a unique "key" prop

After some discussion with @timneutkens and @jxnblk we think it makes most sense to allow layout to be optionally specified in frontmatter.

---
title: Awesome Page
slug: /awesome
layout: ./PageLayout
team:
  - jxn
  - mrmrs
  - johno
---

Resulting in, when layout is defined, the result would be something similar to:

import PageLayout from './PageLayout'

// ... stuff

export default PostLayout(frontmatter)(Markdown)

Something to consider: Should a layout be a HOC or standard component?

This breaks:

`<test>`

• black on white
• white on black
• default styling for editor
• no stylesheet at all

And a few other modules 😅

It'd be nice to be able pass in additional components and props to the component scope.

import React from 'react'
import { Box } from './ui'
import Document from './doc.md'

export default () => <Document scope={{ title: 'Hello', Box }} />

# This is some markdown

That has `Box` and `title` in scope:

<Box>{title}</Box>

Use this to add any thoughts/criticisms/etc. to the MDX and MDXAST specs <3.

Some thoughts inspired by rauchg's .mdx proposal and an iteration on formalizing c8r/markdown.

Inlining JSX

This is a <Text.span>span</Text.span>.

Code blocks

Specifying .jsx as the language will render the React components.
You can also specify front matter which is passed as props to the components being rendered.

---
foo: bar
---
<Awesome>{props.foo}</Awesome>

Inlining JS

{new Date()}

Providing scope/element mapping

We need to be able to provide components, props,

Perhaps this can be done with a MarkdownProvider and ScopeProvider?

Implementation details

The following detauls need to be sorted out for a solid spec/implementation:

Mdast

Depending on what syntax we arrive at, we will need to transform the MD AST to render the desired components.

Interesting related projects/implementations:

• https://github.com/jamesknelson/mdxc
• https://github.com/andreypopp/reactdown

Loaders for webpack/parcel

import Post from './posts/proposal.mdx'

export default <Post />

Import syntax

Ideas:

• imports as the beginning of a mdx file
• using front matter

Pluggable

Similarly to how remark provides a pluggable API, we should also allow plugins to be passed in.
This allows further customization down the road, and also supporting the existing remark plugin ecosystem (toc, gh integrations, etc).

Linting and prettier

Code blocks and inlined js can be run through prettier at the mdast stage and then re-output to markdown.

I suspect the same will be possible with inlined JSX as well.

Input

Hello, <World some='prop' />

Output

Hello, <World some="prop" />

children props are overridden

<Foo children='bar' />

Children prop is empty because the ast children attribute is used.

unnecessary p tags

<Foo>
  Bar
</Foo>

Results in

<h1>
  <p>Bar</p>
</h1>

complex jsx is borked

<Foo>
  <Bar
    children={props.bar.map(b =>
      <Baz key={b}>{b}</Baz>
    )}
  />
</Foo>

Perhaps stuff like this is where we introduce the .jsx code block back?

Expression based props error

<Foo color={'pink'} />

Errors with (in next example):

Error
Error
    at tokens.reduce.type (http://localhost:3000/_next/-/page/index.js:2090:19)
    at Array.reduce (<anonymous>)
    at parse (http://localhost:3000/_next/-/page/index.js:2084:23)
    at Of.parser (http://localhost:3000/_next/-/page/index.js:823:18)
    at Of.tokenize [as tokenizeBlock] (http://localhost:3000/_next/-/page/index.js:72636:18)
    at Of.parse (http://localhost:3000/_next/-/page/index.js:68441:20)
    at Function.parse (http://localhost:3000/_next/-/page/index.js:80537:45)
    at pipelineParse (http://localhost:3000/_next/-/page/index.js:80284:16)
    at wrapped (http://localhost:3000/_next/-/page/index.js:80139:19)
    at next (http://localhost:3000/_next/-/page/index.js:80102:24)

We're getting a few parsing edge cases pop up for
more complex exports:

• #84
• #85

Perhaps we can slice the original file using the remark positioning metadata?