Please note this repo is in active development. Things are likely to change. Use at your own risk <3.

It's currently tracking an evolving spec defined by:

• MDX
• MDXAST

A fully-featured markdown parser and renderer for ambitious projects. Compiles to React for React-based apps or static site generation. Built with remark and adapted from remark-react/mdxc.

@compositor/markdown provides a few added features that improve the Markdown spec, including component imports, inline JSX, and an optional image syntax.

npm install --save @compositor/markdown

• Fast
• Pluggable
• Element to component mapping
• React component imports/rendering
• Simpler image syntax
• Table of contents support
• GitHub style emojis
• Standalone webpack loader for import Docs from './readme.md' support

You can pass in components for any html element that the markdown compiles to. This allows you to use your existing components and use CSS-in-JS like styled-components.

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

const Heading = props =>
  <h1
    style={{ color: 'tomato' }}
    {...props}
  />

export default () =>
  <Markdown
    text='# Hello, world!'
    components={{ h1 }}
  />

If you'd like to pass your default markdown components to all .md imports in your app you can use the ComponentsProvider:

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

import { Heading as h1 } from './ui'

export default () =>
  <ComponentsProvider components={{ h1 }}>
    <Markdown text='# Hello, world!' />
  </ComponentsProvider>

In addition supporting the full Markdown spec, this project adds syntactic niceties and plugin options.

Similarly to JSX, components can be rendered after an import.

import Graph from './components/graph'

## Here's a graph

<Graph />

If you have markdown that's repeated throughout multiple documents, make them standalone, importing them into the desired documents when needed.

import License from './docs/license.md'
import Contributing from './docs/contributing.md'

# Hello, world!

This is an example markdown document.

<License />

***

<Contributing />

Embedding images is easier to remember, you can link a url or relative file path.

#### A url

Below will render an image:

https://c8r-x0.s3.amazonaws.com/lab-components-macbook.jpg

• png
• svg
• jpg

You can use this library in a few different ways depending on what makes most sense for your project.

import { Layout } from './ui'

import Document from './docs/getting-started.md'

export default () =>
  <Layout>
    <Document />
  </Layout>

import { Markdown } from '@compositor/markdown'

export default () =>
  <Markdown text='# Hello, world!' />

The library accepts a markdown string, and an options object.

const fs = require('fs')
const { md } = require('@compositor/markdown')

const doc = fs.readFileSync('file.md', 'utf8')
const ui = require('./ui')

const reactComponents = md(doc, {
  components: {
    h1: ui.H1,
    p: ui.Text,
    code: ui.Code,
    ...ui
  }
})

This libray also provides a hoc for linkifying elements with an id. This is useful for adding a link to headers.

The following will turn linkify any h1 contained in the markdown:

import React from 'react'

import {
  Markdown,
  ComponentsProvider,
  withIdLink
} from '../src'

const Heading = withIdLink(({
  color = 'tomato',
  children,
  ...props
}) =>
  <h1
    style={{ color }}
    children={`# ${children}`}
    {...props}
  />
)

export default md =>
  <ComponentsProvider components={{ h1: Heading }}>
    <Markdown text={md} />
  </ComponentsProvider>

• markdown
• unified
• remark
• remark-jsx
• remark-react
• mdxc
• remark-toc
• remark-emoji
• IA Markdown Content Blocks
• .mdx proposal
• MDXAST proposal

1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create new Pull Request

Made by Compositor | MIT License