marked-mdx
TypeScript icon, indicating that this package has built-in type declarations

0.0.3 • Public • Published

marked-mdx

This is a proof of concept. Don't use it, I'm just experimenting!

marked-mdx is a truly awful way to write "JSX" in markdown (like mdx) but only using marked.

Why

  1. I don't want to use mdx, because it's big and really slow.
  2. I felt like it.

I write my blog using simple markdown that is rendered with marked. Sometimes, I'd like to embed a React component. The components I want to use are simple, usually just accepting a few props or children.

How

marked-mdx allows you to render React components by writing custom HTML tags in your markdown. Let's say you're using marked:

import marked from 'marked'
 
const renderer = new marked.Renderer()
 
marked.setOptions({
  // ...
  renderer
})
 
export default markdown => marked(markdown)

When you want to embed your React component (let's say a graph):

import marked from 'marked'
+ import markedMDX from 'marked-mdx'
+ import graph from '/path/to/graph/component'
 
const renderer = new marked.Renderer()
 
+ const components = {
+   'graph-component': {
+     component: graph
+   }
+ }
 
+ markedMDX(renderer, components)
 
marked.setOptions({
  // ...
  renderer
})
 
export default markdown => marked(markdown)

In your markdown, use your React component using custom HTML tags:

# My Post
 
Yeah this is my post! Using **markdown**!
 
## This Graph
 
Look at this graph
 
<graph-component />

API

markedMDX(renderer, options)

renderer

The renderer you get from marked.

const renderer = new marked.Renderer()

options

An object of mappings from HTML tag names to React components. Each mapping should contain a component and props field.

const options = {
  'html-tag-name': {
    component: ReactComponent,
    props: {...}
  }
}

props should also be a mapping, but from HTML attributes to your React component prop names:

const options = {
  'html-tag-name': {
    component: ReactComponent,
    props: {
      // The HTML attribute `data-theme` will be passed as the `theme` prop to ReactComponent
      'data-theme': 'theme'
    }
  }
}

Usage

Once you have your configuration set up, using marked-mdx in your markdown is easy. Let's say your setup looks like this:

const Header = ({ bold, children }) => {
  return <h1>{bold ? <b>{children}</b> : {children}}</h1>
}
 
const options = {
  header-component: {
    component: Header,
    props: {
      // The HTML attribute `data-theme` will be passed as the `theme` prop to ReactComponent
      'data-bold': 'bold'
    }
  }
}

You can use your component in markdown files like so:

# A regular markdown header
 
<header-component>
  Super cool React header
</header-component>
 
<header-component data-bold>
  This one is bold
</header-component>

The HTML attribute data-bold will be converted to the React prop bold as per the configuration.

Complex Props

Using more complex data (like arrays, objects) as props is also supported if you write them in JSON format.

<graph-component data-entries="[4, 12, 56, 7, 100]">
<!-- The React prop will be the JS array [4, 12, 56, 7, 100] -->
 
<graph-component data-options="{ 'theme': 'blue' }">
<!-- Use single quotes when writing JSON objects, marked-mdx automatically handles them -->
<!-- The React prop will be the JS object { theme: 'blue' } -->

Readme

Keywords

none

Package Sidebar

Install

npm i marked-mdx

Weekly Downloads

0

Version

0.0.3

License

MIT

Unpacked Size

5.68 kB

Total Files

6

Last publish

Collaborators

  • paco