nast-util-to-react

Render a NAST to JSX.Element or HTML.

Documentation

• Usage
• API Reference
• Note
• Develop

Usage

npm i nast-util-to-react

Then,

// CommonJS Module style
const { renderToHTML, renderToJSX } = require('nast-util-to-react');
// or ES Module style
import { renderToHTML, renderToJSX } from 'nast-util-to-react';

API Reference

:warning: This is a beta software, where APIs may change in near future!

renderToHTML(tree)

Render a tree to HTML. This is just a wrapper that use ReactDOMServer.renderToStaticMarkup() to generate HTML from the return value of renderToJSX().

tree

Type: NAST.Block

@returns

Type: string

A HTML string.

renderToJSX(tree)

Render a tree to JSX.Element.

tree

Type: NAST.Block

@returns

Type: JSX.Element

This can be used as a child in a React component, which means it's easier to apply further processing, also it has a small benefit, which is that no dangerouslySetInnerHTML is needed.

Note

Implemented NAST Blocks

Block Capabilities

• [ ] Block can have color or background color.

  Status: See commit 0a51743

  • [ ] Smart color inference based on the following rules.

    Status: See commit 0a51743

    (I = Block)
    If I have a color, I use my color.
    If I don't have a color, I ask my parent for it.
    If I don't have a parent, then just pretend I have a color.

• [ ] Smart layout (full width, page width, normal) for some media blocks and embed blocks.

  Status: Image has best support, others have different partial support.

  Note: Images larger than page width but smaller than full width are unsupported and are displayed as page width.

  This feature should be moved to a wrapper block where all blocks can use if needed.

• [x] Caption in media blocks and embed blocks.

Inline (SemanticString)

• [x] Bold, Italic, Strike, Link, Code, Colored, Commented.

• [x] Mention an Individual

  Shows the individual's name.

• [x] Mention a Resource

  Show the resource's name.

• [x] Mention a DateTime

  Support start_date and end_date.

Basic Blocks

• [x] Text

• [x] Embedded Page / Link To Page

  Gotcha 1: Empty pages and filled pages has the same "filled" icon.

  Gotcha 2: Embedded Page and Link To Page looks the same.

• [x] Heading (1, 2, 3)

• [x] Bulleted List

• [x] Numbered List

• [x] Toggle List

• [x] To-do List

• [x] Quote

• [x] Divider

• [x] Callout

Database Blocks

• [x] Table

  Gotcha 1: Only property types "Title", "Text", "URL", "Checkbox", "Select", "Multi-select" are correctly supported, other types are treated as "Text".

  Gotcha 2: Always wrap text.

• [x] Gallery

  Gotcha 1: Only property type "Title" is rendered.

  Gotcha 2: For "Card Preview" option, only "Page Cover" is supported.

• [ ] List

• [ ] Calendar

• [ ] Board

Media Blocks

• [x] Image
• [x] Web Bookmark
• [x] Video
• [x] Audio
• [x] Code
• [x] File

Embed Blocks

• [x] Embed
• [x] PDF

Advanced Blocks

• [x] Table of Contents

• [x] Math Equation

• [ ] Template Button

  Status: The template is directly rendered as children like normal content blocks.

• [ ] Breadcrumb

  Status: Unable to implement in current rendering framework because it does not allow traveling to other pages.

Develop

Auto-detect changes and rebuild.

npm run dev

Generate data for testing.

npm run update-test-data

Test rendering to HTML.

npm run test