{"id":19370059,"url":"https://github.com/bustle/mobiledoc-vdom-renderer","last_synced_at":"2025-04-23T15:31:55.102Z","repository":{"id":57100728,"uuid":"121461732","full_name":"bustle/mobiledoc-vdom-renderer","owner":"bustle","description":"🔮 Render Mobiledoc as VDOM by passing your React or React-like `createElement` function","archived":false,"fork":false,"pushed_at":"2023-02-21T19:44:14.000Z","size":443,"stargazers_count":6,"open_issues_count":1,"forks_count":2,"subscribers_count":26,"default_branch":"master","last_synced_at":"2024-10-13T00:11:33.108Z","etag":null,"topics":["createelement","hyperscript","mobiledoc","preact","react","vdom"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bustle.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-02-14T02:23:43.000Z","updated_at":"2020-03-09T15:47:57.000Z","dependencies_parsed_at":"2022-08-20T21:10:52.821Z","dependency_job_id":null,"html_url":"https://github.com/bustle/mobiledoc-vdom-renderer","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bustle%2Fmobiledoc-vdom-renderer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bustle%2Fmobiledoc-vdom-renderer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bustle%2Fmobiledoc-vdom-renderer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bustle%2Fmobiledoc-vdom-renderer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bustle","download_url":"https://codeload.github.com/bustle/mobiledoc-vdom-renderer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":223926857,"owners_count":17226455,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["createelement","hyperscript","mobiledoc","preact","react","vdom"],"created_at":"2024-11-10T08:14:06.314Z","updated_at":"2024-11-10T08:14:06.924Z","avatar_url":"https://github.com/bustle.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# mobiledoc-vdom-renderer\n\n[![Build Status](https://travis-ci.org/bustle/mobiledoc-vdom-renderer.svg?branch=master)](https://travis-ci.org/bustle/mobiledoc-vdom-renderer)\n\nThis package renders [Mobiledoc documents](https://github.com/bustle/mobiledoc-kit/blob/master/MOBILEDOC.md) through calls to a `createElement` function, often referred to as `h` (for _[hyperscript](https://github.com/hyperhype/hyperscript)_) or provided as a global if you are using [JSX](https://facebook.github.io/jsx/). This allows embedding Mobiledoc content “natively” as _virtual DOM_ in frameworks like [React](https://reactjs.org/), [preact](https://preactjs.com/), or [hyperapp](https://github.com/hyperapp/hyperapp).\n\nAlternatively, you can skip the “virtual” step and build DOM directly with a micro-renderer such as [ultradom](https://github.com/JorgeBucaran/ultradom) or even convert _mobiledocs_ to arbitrary ASTs by adopting `createElement`’s standard `(type: (properties: object) =\u003e Node, properties: object, ...children: Node[]) =\u003e Node` signature for your builder.\n\n## Installation\n\n```shell\nnpm install mobiledoc-vdom-renderer --save\n```\n\nor\n\n```shell\nyarn add mobiledoc-vdom-renderer\n```\n\n## Usage\n\n```jsx\n/* @jsx h */\nimport Renderer from 'mobiledoc-vdom-renderer'\n\n// render: (mobiledoc: Mobiledoc) =\u003e Node[]\nconst render = Renderer({ createElement: h })\n\n// Instant \u003cMobiledoc/\u003e Component\nexport default function Mobiledoc({ mobiledoc }) {\n  return \u003cdiv\u003e{render(mobiledoc)}\u003c/div\u003e\n}\n```\n\n## API\n\n```javascript\nimport Renderer, { upgradeMobiledoc } from 'mobiledoc-vdom-renderer'\n```\n\n### `Renderer` _(default export)_\n\n```typescript\nRenderer: (options: RendererOptions) =\u003e RenderFunction\n```\n\nCreates a _render function_ (`(mobiledoc: Mobiledoc) =\u003e Node[]`) from the supplied options\n\n- #### `options` _required_\n  ```typescript\n  {\n    createElement: CreateElement,\n    getCardComponent?: ComponentGetter,\n    getAtomComponent?: ComponentGetter,\n    getMarkupComponent?: ComponentGetter = getMarkupComponentDefault\n  }\n  ```\n  - ##### `createElement` _required_\n    ```typescript\n    createElement: (\n      type: string | Component,\n      properties?: object,\n      ...children: Node[]\n    ) =\u003e Node\n    ```\n    Any compatible function such as `React.createElement` or hyperscript `h`\n  - ##### `getCardComponent`\n    ```typescript\n    getCardComponent: (type: string) =\u003e string | Component\n    ```\n    Function which returns a string (_tag name_) or _component_ (`(properties: { payload: object }) =\u003e Node`) for the given _card type_ (required if rendering a mobiledoc with cards)\n  - ##### `getAtomComponent`\n    ```typescript\n    getAtomComponent: (type: string) =\u003e string | Component\n    ```\n    Function which returns a string (_tag name_) or _component_ (`(properties: { payload: object }) =\u003e Node`) for the given _atom type_ (required if rendering a mobiledoc with atoms)\n  - ##### `getMarkupComponent`\n    ```typescript\n    getMarkupComponent: (tagName: string) =\u003e string | Component = getMarkupComponentDefault\n    ```\n    Function which returns a string (_tag name_) or _component_ (`(attributes: object) =\u003e Node`) to override rendering for the given tag name (for instance, to mix in HTML attributes or render a custom component instead)\n    ```typescript\n    import { getMarkupComponentDefault } from 'mobiledoc-vdom-renderer'\n    ```\n    `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](./types/Mobiledoc/0.3/index.ts); passing through all tag names instead (as in `tagName =\u003e tagName`) allows (non-standard) mobiledocs containing arbitrary tags to be rendered\n\n### `upgradeMobiledoc`\n\n```typescript\nupgradeMobiledoc: (mobiledoc: Mobiledoc | Mobiledoc02x) =\u003e Mobiledoc\n```\n\nUpgrades a mobiledoc from any released version to the latest specification (`0.3.1`)\n\n## Type definitions\n\n```typescript\nimport { Mobiledoc, MobiledocTypes } from 'mobiledoc-vdom-renderer'\n```\n\nThis package includes [complete Typescript definitions describing the Mobiledoc format](./types/Mobiledoc/0.3/index.ts), which may be imported directly for use with any mobiledoc-related code.\n\n## Contributing\n\nContributions—including pull requests, bug reports, documentation, and suggestions—are welcome!\n\nThe code is written in [Typescript](http://www.typescriptlang.org/) 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.\n\n### Test-driven development\n\n- #### Installation\n\n```shell\ngit clone https://github.com/bustle/mobiledoc-vdom-renderer.git\ncd mobiledoc-vdom-renderer/\nnpm install\n```\n\n- #### `npm start`\n\n  Watches the filesystem for changes ([chokidar-cli](https://github.com/kimmobrunfeldt/chokidar-cli)) then lints (Typescript, [Standard style](https://standardjs.com/), [functional JS practices](https://github.com/jfmengels/eslint-plugin-fp)) and tests ([ava snapshots](https://github.com/avajs/ava#snapshot-testing)) each file you touch\n\n- #### Other useful commands\n  - ##### `npm test`\n    Run the linters and all tests and generate a coverage report ([nyc](https://github.com/istanbuljs/nyc))\n  - ##### `npm run snapshot`\n    Updates all snapshots; check your `git` diff before committing!\n  - ##### `npm run format`\n    Fixes many linting errors and applies [prettier whitespace conventions](https://github.com/prettier/prettier)\n\n## More for Mobiledoc\n\n### Renderers\n\n- [mobiledoc-react-renderer](https://github.com/dailybeast/mobiledoc-react-renderer)\n- [mobiledoc-dom-renderer](https://github.com/bustle/mobiledoc-dom-renderer)\n- [mobiledoc-text-renderer](https://github.com/bustle/mobiledoc-text-renderer)\n\n### Editors\n\n- [react-mobiledoc-editor](https://github.com/joshfrench/react-mobiledoc-editor)\n- [ember-mobiledoc-editor](https://github.com/bustle/ember-mobiledoc-editor)\n- [vue-mobiledoc-editor](https://github.com/alidcastano/vue-mobiledoc-editor)\n\n### Utilities\n\n- [mobiledoc-kit](https://github.com/bustle/mobiledoc-kit) editor toolkit\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbustle%2Fmobiledoc-vdom-renderer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbustle%2Fmobiledoc-vdom-renderer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbustle%2Fmobiledoc-vdom-renderer/lists"}