Render Mobiledoc as VDOM, for React or React-like `createElement` calls
npm install 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.
``shell`
npm install mobiledoc-vdom-renderer --save
or
`shell`
yarn add mobiledoc-vdom-renderer
`jsx
/ @jsx h /
import Renderer from 'mobiledoc-vdom-renderer'
// render: (mobiledoc: Mobiledoc) => Node[]
const render = Renderer({ createElement: h })
// Instant
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`- mobiledoc-react-renderer
- mobiledoc-dom-renderer
- mobiledoc-text-renderer
- react-mobiledoc-editor
- ember-mobiledoc-editor
- vue-mobiledoc-editor
- mobiledoc-kit editor toolkit