{"id":19370084,"url":"https://github.com/bustle/mobiledoc-dom-renderer","last_synced_at":"2025-04-07T05:11:03.496Z","repository":{"id":1068689,"uuid":"38825919","full_name":"bustle/mobiledoc-dom-renderer","owner":"bustle","description":null,"archived":false,"fork":false,"pushed_at":"2023-04-28T18:35:51.000Z","size":622,"stargazers_count":25,"open_issues_count":8,"forks_count":18,"subscribers_count":13,"default_branch":"master","last_synced_at":"2025-03-30T21:13:42.509Z","etag":null,"topics":["dom-renderer","mobiledoc","mobiledoc-kit"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bustle.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2015-07-09T14:39:27.000Z","updated_at":"2022-12-14T09:35:18.000Z","dependencies_parsed_at":"2023-07-05T19:48:45.463Z","dependency_job_id":null,"html_url":"https://github.com/bustle/mobiledoc-dom-renderer","commit_stats":{"total_commits":138,"total_committers":12,"mean_commits":11.5,"dds":0.5,"last_synced_commit":"a950f0c59a3a0482152950ee5dd924a9b09a7abe"},"previous_names":[],"tags_count":51,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bustle%2Fmobiledoc-dom-renderer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bustle%2Fmobiledoc-dom-renderer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bustle%2Fmobiledoc-dom-renderer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bustle%2Fmobiledoc-dom-renderer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bustle","download_url":"https://codeload.github.com/bustle/mobiledoc-dom-renderer/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247595335,"owners_count":20963943,"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":["dom-renderer","mobiledoc","mobiledoc-kit"],"created_at":"2024-11-10T08:14:11.355Z","updated_at":"2025-04-07T05:11:03.476Z","avatar_url":"https://github.com/bustle.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"## Mobiledoc DOM Renderer\n\nThis is a DOM renderer for the [Mobiledoc format](https://github.com/bustlelabs/mobiledoc-kit/blob/master/MOBILEDOC.md) used\nby [Mobiledoc-Kit](https://github.com/bustlelabs/mobiledoc-kit).\n\nTo learn more about Mobiledoc cards and renderers, see the **[Mobiledoc Cards docs](https://github.com/bustlelabs/mobiledoc-kit/blob/master/CARDS.md)**.\n\nThe renderer is a small library intended for use in browser clients.\n\n### Usage\n\n```js\nvar mobiledoc = {\n  version: \"0.3.0\",\n  markups: [\"B\"],\n  atoms: [],\n  cards: [],\n  sections: [\n    [1, 'P', [ // array of markers\n      // marker\n      [ 0,            // marker type 0 (standard text)\n        [0],          // open markups (by index)\n        0,            // close count\n        'hello world'\n      ]\n    ]\n  ]\n};\nvar renderer = new MobiledocDOMRenderer({cards: []});\nvar rendered = renderer.render(mobiledoc);\nvar result = rendered.result;\ndocument.getElementById('output').appendChild(result);\n// renders \u003cdiv\u003e\u003cp\u003e\u003cb\u003ehello world\u003c/b\u003e\u003c/b\u003e\u003c/div\u003e\n// into 'output' element\n```\n\nThe Renderer constructor accepts a single object with the following optional properties:\n\n  * `cards` [array] - The list of card objects that the renderer may encounter in the mobiledoc\n  * `atoms` [array] - The list of atom objects that the renderer may encounter in the mobiledoc\n  * `cardOptions` [object] - Options to pass to cards and atoms when they are rendered\n  * `unknownCardHandler` [function] - Will be called when any unknown card is enountered\n  * `unknownAtomHandler` [function] - Will be called when any unknown atom is enountered\n  * `sectionElementRenderer` [object] - A map of hooks for section element rendering.\n    * Valid keys are P, H1, H2, H3, H4, H5, H6, BLOCKQUOTE, ASIDE\n    * Arguments are `tagName, dom`\n    * A valid value is a function that returns an element\n  * `markupElementRenderer` [object] - A map of hooks for inline element rendering.\n    * Valid keys are B, I, STRONG, EM, A, U, SUB, SUP, S, CODE\n    * Arguments are `tagName, dom, attributes={}`\n    * A valid value is a function that returns an element\n  * `dom` [object] - A native or [SimpleDOM](https://github.com/krisselden/simple-dom)\n    implementation of the DOM.\n\nThe return value from `renderer.render(mobiledoc)` is an object with two properties:\n  * `result` [DOM Node] - The rendered result\n  * `teardown` [function] - When called, this function will tear down the rendered mobiledoc and call any teardown handlers that were registered by cards when they were rendered\n\n#### Rendering HTML\n\nIn a browser, rendering to HTML is simple:\n\n```js\nvar renderer = new MobiledocDOMRenderer();\nvar rendered = renderer.render(mobiledoc);\nvar html = rendered.result.outerHTML;\n```\n\nHowever on the server in Node.js, native DOM APIs are not available. To make\nserver-rendering easy, this DOM\nrenderer is [SimpleDOM](https://github.com/krisselden/simple-dom)\ncompatible. You may pass an instance of a SimpleDOM document and serialize\nits output. For example:\n\n```js\nvar renderer = new MobiledocDOMRenderer({\n  dom: new SimpleDOM.Document()\n});\nvar rendered = renderer.render(mobiledoc);\nvar serializer = new SimpleDOM.HTMLSerializer([]);\nvar html = serializer.serializeChildren(rendered.result);\n```\n\nThis usage of the DOM renderer for rendering HTML has the advantage of allowing\ndevelopers to easily implement cards that work in a server and client context.\n\n#### sectionElementRenderer\n\nUse this renderer option to customize what element is used when rendering\na section.\n\n```\nvar renderer = new MobiledocDOMRenderer({\n  sectionElementRenderer: {\n    P: function(_, dom) { return dom.createElement('span'); },\n    H1: function(_, dom) { return dom.createElement('h2'); },\n    H2: function(tagName, dom) {\n      var element = dom.createElement(tagName);\n      element.setAttribute('class', 'subheadline');\n      return element;\n    }\n    /* Valid keys are P, H1, H2, H3, H4, H5, H6, BLOCKQUOTE, ASIDE */\n  }\n});\nvar rendered = renderer.render(mobiledoc);\n```\n\n#### markupElementRenderer\n\nUse this renderer option to customize what inline tags are used when rendering\na section's content.\n\n```\nvar renderer = new MobiledocDOMRenderer({\n  markupElementRenderer: {\n    B: function(_, dom) { return dom.createElement('strong'); },\n    A: function(tagName, dom, attrs={}) {\n      let element = dom.createElement(tagName);\n\n      for (let attr in attrs) {\n        element.setAttribute(attr, attrs[attr]);\n      }\n\n      element.setAttribute('rel', 'nofollow');\n      return element;\n    }\n  }\n});\nvar rendered = renderer.render(mobiledoc);\n```\n\n#### Attribute Sanitization (XSS Protection)\n\nMobiledoc DOM Renderer sanitizes the `href` attribute of 'A' markups, prefixing\nthe string `unsafe:` on potentially unsafe urls. It determines an environment-\nappropriate URL protocol parser. In rare cases it may be unable to determine one\n(this can happen when running the renderer in a Node VM Sandbox, like ember-cli-\nfastboot does), and will throw in that case. To fix this, you can provide a\ncustom markupElementRenderer for the 'A' tag that will be used instead of the\ndefault.\n\n### Tests\n\n * To run tests via testem: `npm test`\n * To run tests in the browser: `npm start` and open http://localhost:4200/tests\n\n### Releasing\n\n* Use `np` (install with `npm install -g np`)\n* `np \u003cversion\u003e` (e.g. `np 0.5.2`)\n* `git push --tags`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbustle%2Fmobiledoc-dom-renderer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbustle%2Fmobiledoc-dom-renderer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbustle%2Fmobiledoc-dom-renderer/lists"}