How To: Use Custom Blocks

Custom block feature lets you extend your markdown content extremely easily and versatile with react components. You can call external http api requests in the blocks and also easily integrated with 3rd party apps like GitHub.(Now we're only support github but we will add more soon.)

Create a block

Click New Button in Blocks page

Create a custom block

Name

The name will be used like tag name to embed the block. Once the block is created, you can embed the block by inserting <BlockName /> in any documents in your Boost Hub workspace.

Code

Code should be javascript or typescript code which is exporting a react component as default. Boost Hub will compile the custom block code internally and runs it in browser when the block is rendered. You can do anything you want. You declare any functions and any sub components as many as you want.

fetchData

It is an extra life cycle for fetching data via http. You can provide any function which returning a Promise. Once the promise is returned, BoostHub markdown renderer will resolve and provide it to its rendered components via data prop.

Lots of React components is using useEffect to fetch data after mounted. The problem is that the fetching request in useEffect hook is called too often because the components are remounted every content change in markdown preview. This might cause your api token to hit its usage limitation too fast. So we recommend you to use this custom life cycle to fetch data. It will be called periodically and manually by clicking a refresh button near the rendered custom block.

import React from 'react'
const MyBlock = ({ data }) => {
  return (
    <...>{doSomethingWithData(data)}<.../>
  )
}

MyBlock.fetchData = async () => {
  const response = await fetch(...)
  const data = await response.json()
  
  return data
}

export default MyBlock

Integrations

With this, you can integrate 3rd party app with a custom block very easily. Once you select 3rd party integration, Boost Hub will provide their client instance. So you can use their api directly without fetching and storing an access token manually. For now, we only support GitHub. Once you select GitHub integration, github prop will be available in the default react component and fetchData method.

Here's an example which is fetching github issues from some repository.

import React from 'react'
const MyBlock = ({ github, data }) => {
  const issues = data
  
  const createIssue = useCallback(async () => {
    const response = await github.issues.create(...)
    ...              
  }, [github])
  
  return (
    <div>
      <ul>{issues.map(...)}</ul>
      <button onClick={createIssue}>Create</button>
    </div>
  )
}

MyBlock.fetchData = async ({ github }) => {
  const { data } = await github.issues.listForRepo({
    owner: 'BoostIO',
    repo: 'BoostNote.next',
    state: 'open',
  });
  return data
}

export default MyBlock

Use a block

All custom blocks are available in any documents by inserting its name like this, <CustomBlockName/>.

If you don't remember the name, you can click Blocks on right top of your screen. Then it will show a list of custom blocks available in your workspace. Once you click select button of a custom block in the list, Boost Hub will insert the block to markdown content.