@sanity/block-content-to-html

block-content-to-html-js

Converts the flat Sanity block content structure into HTML.

Installation

npm install --save @sanity/block-content-to-html

Quick example

// The flat block content structure
const data = {
  "_type": "block",
  "style": "normal",
  "spans": [
    {
      "_type": "span",
      "text": "String with an ",
      "marks": []
    },
    {
      "_type": "span",
      "text": "italicized",
      "marks": [
        "em"
      ]
    },
    {
      "_type": "span",
      "text": " word.",
      "marks": []
    }
  ]
}


// Now convert it with block-content-to-html
const BlockContentToHtml = require('@sanity/block-content-to-html')
const toHtml = new BlockContentToHtml()

const html = toHtml.convert(data)

This will result in html being:

<p>String with an <em>italicized</em> word.</p>

Interface

The constructor will take an object for options:

const toHtml = new BlockContentToHtml(options: Object)

Converting the block content is done by calling .convert:

toHtml.convert(data: Array|Object)

Constructor options

Options is an object with any of the following keys:

{
  customTypeHandlers: {
    ...
  },
  blockTypeHandlers: {
    textBlock: {
      ...
    },
    listBlock: {
      ...
    },
    span: {
      ...
    },
    marks: {
      ...
    }
  }
}

Read below for a closer description of each option.

customTypeHandlers: Object

An object with keys for your custom block types. Each key is mapped to a type, and their value is a function which will get the node as input. It returns HTML.

customTypeHandlers: {
  author: node => {
    return `<div>${node.attributes.name}</div>`
  }
}

The node in this example has the following structure:

{ type: 'author', attributes: { name: 'Test Person' } }

Normally you don't register the block type here, which is handled through the blockTypeHandlers.textBlock option. However, you may register block here to deal with them on your own, or if you just want to wrap all block types in some special markup. You call the second parameter with the node to get the output of the default handler which is set up through the blockTypeHandlers.textBlock option (see below).

block: (node, defaultFn) => {
  return `<div class="grid 7">${defaultFn(node)}</div>`
}

blockTypeHandlers: Object

Handlers for manipulating the output of the default, built in, block types. The default block type holds either a block of text or a list. A text block is built up of spans (with marks), where a list block is built up of list items, which can contain a text block.

The blockTypeHandlers object can contain the follow keys:

• textBlock: Object

  Each text block has a style property. With this option you can manipulate how each style is rendered. By default the basic style normal is wrapped in a <p> tag, where other default styles are mapped 1:1 (style h2 produces <h2>).

  The option works in a similar way as customTypeHandlers described above, with the distinction that is has a children property, and the key is the style name:

  textBlock: {
    normal: node => {
      return `<div class="funky-paragraph">${node.children}</div>`
    },
    h2: node => {
      return `<div class="big-heading">${node.children}</div>`
    }
  }
  

• listBlock: Object

  By default lists are rendered with plain <ol>, <ul>and <li> tags. With this option you can tweak them into your own liking.

  The object takes the following keys:

  listBlock: {
    number: node => {
      return `<ol class="article-list">${node.children}</ol>`
    },
    bullet: node => {
      return `<ul class="article-list">${node.children}</ul>`
    },
    listItem: node => {
      return `<li class="article-list-item ${node.style}">${node.children}</li>`
    }
  }
  

  Note that the listItem handler has a style property. This is because each of the block content's list items can be formatted with an individual text style. If you want this to be reflected in your HTML output you have to deal with it yourself. The default is just to wrap the pure text content within a <li> tag.

• span: Object

  Let you tweak how spans within blocks are rendered. By default the spans are just text and marks. As spans may have attributes with data, you can make your own render which manipulates the output based on their attributes:

  span: node => {
    let result = ''
    if (node.attributes.author) {
      result = `
        <div class="author-bio">
          <img src="${node.attributes.author.image.url}" />
          ${node.attributes.author.name}
        </div>`
    }
    if (node.attributes.link) {
      result += `<a href="${node.attributes.link.href}">${node.children}</a>`
    }
    if (Object.keys(node.attributes).length === 0) {
      result = node.children
    }
    return result
  }
  

• marks: Object

  Marks are by default mapped 1:1. If the mark is 'em' the output will be <em>. With this option you can map marks to other tags, or just ignore them:

  marks: {
    em: null // Just igonore 'em' marks.
    code: 'pre' // Render 'code' marks as 'pre' tags
  }
  

Custom data on the block content

block-content-to-html supports setting custom data on the original block content through setting a .extra property on a block element. This is handy if you want to generate and keep track of a HTML id attribute, or other arbitrary data related to rendering.

The value can be anything you like.

Example:

const blockContent = {
  "_type": "block",
  "style": "h2",
  "extra": "header_1234", // Our extra property added to the original content.
  "spans": [
    {
      "_type": "span",
      "text": "Such h2 header, much amaze",
      "marks": []
    }
  ]
}

const toHtml = new BlockContentToHtml({
  blockTypeHandlers: {
    textBlock: {
      h2: node => {
        const htmlId = node.extra // Here it is available for us
        return `<h2 id="${htmlId}">${node.children}</h2>`
      }
    }
  }
})

const html = toHtml.convert(blockContentdata)

Resulting in html being:

<h2 id="header_1234">Such h2 header, much amaze</h2>

Utility function

BlockContentToHtml.escapeHtml(unsafe: string)

Escape unsafe text to HTML safe text. To be used with your own handler functions.

More information / examples

Please see the tests.

License

MIT-licensed