Using D2 diagram in Docusaurus

Overview

I found a awesome third party library for Docusaurus.

I'd like to show you how I applied it.

How it works

Basically It's bunch of a codeblock as we commonly use.

same old codeblock like this.

Sequence diagram of how it works

How to use D2

If you want advanced configuration see the Offical document

Installation

$ npm install remark-kroki --save-dev

Usage

// docusaurus.config.ts
import { remarkKroki } from "remark-kroki";

export default {
  presets: [
    [
      // you might find "@docusaurus/preset-classic" but no worry.  Those are same thing.
      "classic",
      {
        docs: {
          remarkPlugins: [[remarkKroki, { server: "https://kroki.io" }]],
          rehypePlugins: [
            [
              rehypeRaw,
              {
                passThrough: [
                  "mdxFlowExpression",
                  "mdxJsxFlowElement",
                  "mdxJsxTextElement",
                  "mdxTextExpression",
                  "mdxjsEsm",
                ],
              },
            ],
          ],
        },
      },
    ],
  ],
};

If you want to use your own kroki server, set http://localhost:${port}. I recommend to use personal kroki server using docker image.

Cloudflare blocks your request at some point.

Git Action Deployment

Down below is the yaml script to deploy docusaurus in git action.
Add highlighted code block.

name: Deploy to GitHub Pages

on:
  push:
    branches:
      - main

jobs:
  build:
    name: Build Docusaurus
    runs-on: ubuntu-latest

    ## add this
    services:
      kroki:
        image: yuzutech/kroki:latest
        ports:
          - "8000:8000"

    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 18
          cache: npm

      - name: Install dependencies
        run: npm install
      - name: Build website
        run: npm run build
      - name: Upload Build Artifact
        uses: actions/upload-pages-artifact@v3
        with:
          path: build

  deploy:
    name: Deploy to GitHub Pages
    needs: build

    # Grant GITHUB_TOKEN the permissions required to make a Pages deployment
    permissions:
      pages: write # to deploy to Pages
      id-token: write # to verify the deployment originates from an appropriate source

    # Deploy to the github-pages environment
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    runs-on: ubuntu-latest
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

By this, You can approach http://localhost:8000 to make d2 diagram while build action is in process.

Reference

• Discussion about D2 native support in docusaurus
• Gitbug of remark-kroki