gatsby-source-roamresearch

Source plugin for pulling data into Gatsby from Roam Research. It creates links between pages so they can be queried in Gatsby using GraphQL.

An example site for using this plugin is at https://mathieudutour.github.io/gatsby-digital-garden/

Install

npm install --save gatsby-source-roamresearch

How to use

First, you need a way to pass environment variables to the build process, so secrets and other secured data aren't committed to source control. We recommend using dotenv which will then expose environment variables. Read more about dotenv and using environment variables here. Then we can use these environment variables and configure our plugin.

// In your gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-source-roamresearch`,
      options: {
        url: `https://roamresearch.com/#/app/YOUR_DATABASE_HERE`,
        // Learn about environment variables: https://gatsby.dev/env-vars
        email: process.env.ROAM_RESEARCH_EMAIL,
        password: process.env.ROAM_RESEARCH_PASSWORD,
      },
    },
  ],
};

Configuration options

url [string][required]

Url to the Roam Research database

email [string][required]

Email used to sign into Roam Research

password [string][required]

Password used to sign into Roam Research

How to query for nodes

Two standard node types are available from Roam Research: Page and Block.

The nodes will be created in your site's GraphQL schema under roam${entryTypeName} and allRoam${entryTypeName}.

In all cases querying for nodes like roamX will return a single node, and nodes like allRoamX will return all nodes of that type.

Query for all nodes

You might query for all of a type of node:

{
  allRoamPage {
    nodes {
      id
      title
    }
  }
}

You might do this in your gatsby-node.js using Gatsby's createPages Node API.

Query for a single node

To query for a single block with the id 'foo':

export const blockQuery = graphql`
  {
    roamBlock(id: "foo") {
      string
    }
  }
`;

You might query for a single node inside a component in your src/components folder, using Gatsby's StaticQuery component.

A note about markdown fields

Roam Research uses Markdown for its formatting.

In order to handle the Markdown content, you must use a transformer plugin such as gatsby-transformer-remark or gatsby-plugin-mdx. The transformer will create a childMarkdownRemark field on the node and expose the generated html as a child node:

{
  roamBlock {
    childMarkdownRemark {
      html
    }
  }
}

You can then insert the returned HTML inline in your JSX:

<div
  className="body"
  dangerouslySetInnerHTML={{
    __html: data.roamBlock.childMarkdownRemark.html,
  }}
/>

Note that Roam Research uses some non-standard syntax for its internal links, so you will need some additional plugins to handle them (for example gatsby-remark-double-brackets-link and gatsby-remark-double-parenthesis-link).

In order to extract the references between the nodes, you can use gatsby-transformer-markdown-references.

Sourcing From Multiple Roam Research databases

To source from multiple Roam Research databases, add another configuration for gatsby-source-roamresearch in gatsby-config.js:

// In your gatsby-config.js
module.exports = {
  plugins: [
    {
      resolve: `gatsby-source-roamresearch`,
      options: {
        url: `https://roamresearch.com/#/app/YOUR_DATABASE_HERE`,
        email: process.env.ROAM_RESEARCH_EMAIL,
        password: process.env.ROAM_RESEARCH_PASSWORD,
      },
    },
    {
      resolve: `gatsby-source-roamresearch`,
      options: {
        url: `https://roamresearch.com/#/app/YOUR_SECOND_DATABASE_HERE`,
        email: process.env.ROAM_RESEARCH_SECOND_EMAIL,
        password: process.env.ROAM_RESEARCH_SECOND_PASSWORD,
      },
    },
  ],
};