For those of you that are new, Dolt is a database that supports Git-style versioning. DoltHub is a place on the internet to share and collaborate on Dolt databases. We are excited to announce a new feature in our documentation that showcases Dolt system tables and functions and enables direct interaction with the DoltHub SQL console from within our documentation site and blog. In this blog post, we will introduce you to this new feature and provide a brief explanation of how we built it in GitBook.

The Embedded DoltHub SQL Console

We have incorporated informative examples within our Dolt system tables documentation, allowing you to experiment with Dolt SQL queries without ever leaving our documentation.

We've also integrated the DoltHub SQL Console directly into our blog! It's much easier to embed a url in Gatsby, since it supports iframe. Try it out:

Below is the code snippet that enables the embedding of the DoltHub SQL Console in our blog:

<iframe
  src="https://www.dolthub.com/repositories/dolthub/docs_examples/embed/main?q=SELECT+*+from+dolt_commit_diff_mytable+where+to_commit%3DHASHOF%28%27feature%27%29+and+from_commit+%3D+HASHOF%28%27main%27%29%3B"
  width="700"
  height="420"
  name="dolthub-embed"
></iframe>

The GitBook Embedding Integration

Our documentation is powered by GitBook. Integrating external URLs in GitBook was a challenging task, as the standard approach using a raw iframe didn't work as expected. To enable the embedded DoltHub SQL console in our docs, we have implemented a custom embedding integration.

Initial attempt

Following the GitBook documentation, I set the integration block's id to be embedDoltHubSQL, which is a custom name for our integration block. Then I published and installed the it successfully. However, we prefer editing our docs using markdown, and the instructions for GitBook integration in markdown were not as clear. The provided guide mentioned a syntax line {% myintegration/block-name propA="A" %}, but I struggled to understand what to replace myintegration with. To figure it out, I inserted an embedded block and synced it to our GitHub docs repository, which revealed the syntax:

{% @embedDoltHubSQL/embedDoltHubSQL embedUrl="https://www.dolthub.com" %}

When I attempted to write this line in markdown and publish it in GitBook, I encountered an issue where the system automatically escaped the { and } characters, resulting in:

\{% @embedDoltHubSQL/embedDoltHubSQL embedUrl="https://www.dolthub.com" %\}

As a result, the embedded web frame appeared as plain text and the markdown was not parsed correctly. After discussing the problem with the GitBook support team, they confirmed that this was a broken feature, and they removed the line {% myintegration/block-name propA="A" %} from their guide. Fortunately, I discovered a workaround to make the integration function correctly in markdown.

Finding a successful workaround

To make the integration work within markdown, I had to modify the blocks ID in the gitbook-manifest.yaml file and the componentId in our integration component to be embed instead of a custom name. Here are the steps we followed to achieve the desired outcome:

Configuring gitbook-manifest

The gitbook-manifest.yaml file provides the configuration for our integration. It specifies the integration's name, title, organization, visibility, and description. It also defines the supported blocks, such as the "embed" block that triggers the embedded SQL console. GitBook needs to identify which integration can handle specific URLs. To do so, integration blocks should be configured to list url patterns that can be unfurled:

blocks:
  - id: embed
    title: Embed DoltHub SQL
    description: Embed URL on DoltHub
    urlUnfurl:
      - https://www.dolthub.com/repositories/**

Integration Component

The embedBlock component determines the behavior when unfurling a DoltHub URL and renders the SQL console with the appropriate aspect ratio.

In this component, the action method defines the behavior when a specific action is triggered. In this case, it handles the @link.unfurl action and extracts the URL from the action.

  async action(element, action) {
    switch (action.action) {
      case "@link.unfurl": {
        const { url } = action;

        return {
          props: {
            url,
          },
        };
      }
    }

    return element;
  },

Add the render method which specifies how the block should be rendered. It takes the URL and uses it to construct a webframe block, which renders an external URL.

  async render(element, context) {
    const { url } = element.props;
    const aspectRatio = 16 / 9;
    return (
      <block>
        <webframe
          source={{
            url: url,
          }}
          aspectRatio={aspectRatio}
        />
      </block>
    );
  },

We can now embed our DoltHub SQL console page in the documentation markdown using the following syntax:

{% embed url="https://www.dolthub.com/repositories/dolthub/docs_examples/embed/main?q=SELECT+*+from+dolt_commit_diff_mytable+where+to_commit%3DHASHOF%28%27feature%27%29+and+from_commit+%3D+HASHOF%28%27main%27%29%3B" %}

Conclusion

You can check out the integration code here. We hope this new feature enhances your experience and empowers you to make the most of our documentation! Feel free to reach out to any of our team members on Discord.