mobiledoc-vdom-renderer


This package renders Mobiledoc documents through calls to a createElement function, often referred to as h (for _hyperscript_) or provided as a global if you are using JSX. This allows embedding Mobiledoc content “natively” as _virtual DOM_ in frameworks like React, preact, or hyperapp.

Alternatively, you can skip the “virtual” step and build DOM directly with a micro-renderer such as ultradom or even convert _mobiledocs_ to arbitrary ASTs by adopting createElement’s standard (type: (properties: object) => Node, properties: object, ...children: Node[]) => Node signature for your builder.

Installation

``shell
npm install mobiledoc-vdom-renderer --save
`

or

`shell
yarn add mobiledoc-vdom-renderer
`

Usage

`jsx
/ @jsx h /
import Renderer from 'mobiledoc-vdom-renderer'

// render: (mobiledoc: Mobiledoc) => Node[]
const render = Renderer({ createElement: h })

// Instant Component
export default function Mobiledoc({ mobiledoc }) {
return


}
`

API

`javascript
import Renderer, { upgradeMobiledoc } from 'mobiledoc-vdom-renderer'
`

$3

`typescript
Renderer: (options: RendererOptions) => RenderFunction
`

Creates a _render function_ ((mobiledoc: Mobiledoc) => Node[]) from the supplied options

- #### options _required_
`typescript
{
createElement: CreateElement,
getCardComponent?: ComponentGetter,
getAtomComponent?: ComponentGetter,
getMarkupComponent?: ComponentGetter = getMarkupComponentDefault
}
`
- ##### createElement _required_
`typescript
createElement: (
type: string | Component,
properties?: object,
...children: Node[]
) => Node
`
Any compatible function such as React.createElement or hyperscript h
- ##### getCardComponent
`typescript
getCardComponent: (type: string) => string | Component
`
Function which returns a string (_tag name_) or _component_ ((properties: { payload: object }) => Node) for the given _card type_ (required if rendering a mobiledoc with cards)
- ##### getAtomComponent
`typescript
getAtomComponent: (type: string) => string | Component
`
Function which returns a string (_tag name_) or _component_ ((properties: { payload: object }) => Node) for the given _atom type_ (required if rendering a mobiledoc with atoms)
- ##### getMarkupComponent
`typescript
getMarkupComponent: (tagName: string) => string | Component = getMarkupComponentDefault
`
Function which returns a string (_tag name_) or _component_ ((attributes: object) => Node) to override rendering for the given tag name (for instance, to mix in HTML attributes or render a custom component instead)
`typescript
import { getMarkupComponentDefault } from 'mobiledoc-vdom-renderer'
`
getMarkupComponent’s default behavior is exported as getMarkupComponentDefault, which passes through valid tag names but throws an error for tags not on Mobiledoc’s _markup section_ or _markup_ whitelists; passing through all tag names instead (as in tagName => tagName) allows (non-standard) mobiledocs containing arbitrary tags to be rendered

$3

`typescript
upgradeMobiledoc: (mobiledoc: Mobiledoc | Mobiledoc02x) => Mobiledoc
`

Upgrades a mobiledoc from any released version to the latest specification (0.3.1)

Type definitions

`typescript
import { Mobiledoc, MobiledocTypes } from 'mobiledoc-vdom-renderer'
`

This package includes complete Typescript definitions describing the Mobiledoc format, which may be imported directly for use with any mobiledoc-related code.

Contributing

Contributions—including pull requests, bug reports, documentation, and suggestions—are welcome!

The code is written in Typescript in a pure functional style. Opinionated “best practices,” including functional programming, are strictly enforced by linters—it’ll help to use a code editor which supports both as-you-type linting and type-checking.

$3

- #### Installation

`shell
git clone https://github.com/bustle/mobiledoc-vdom-renderer.git
cd mobiledoc-vdom-renderer/
npm install
`

- #### npm start

Watches the filesystem for changes (chokidar-cli) then lints (Typescript, Standard style, functional JS practices) and tests (ava snapshots) each file you touch

- #### Other useful commands
- ##### npm test
Run the linters and all tests and generate a coverage report (nyc)
- ##### npm run snapshot
Updates all snapshots; check your git diff before committing!
- ##### npm run format`
Fixes many linting errors and applies prettier whitespace conventions

More for Mobiledoc

$3

- mobiledoc-react-renderer
- mobiledoc-dom-renderer
- mobiledoc-text-renderer

$3

- react-mobiledoc-editor
- ember-mobiledoc-editor
- vue-mobiledoc-editor

$3

- mobiledoc-kit editor toolkit