@gridd/docusaurus-visuals-plugin

Docusaurus plugin that lets MDX pages embed three things from concise markdown shorthand:

• Gridd slides (referenced) — [$Gridd](./asset.json) renders a Gridd embed iframe loading the JSON asset.
• Gridd slides (inline) — ```gridd ``` fenced code blocks with YAML slide content render inline — no separate JSON file needed.
• Recharts — [$Chart](./data.csv) renders a line chart from the CSV; [$BarChart] / [$AreaChart] and ?type=bar|line|area switch chart type.
• D3 diagrams — [$D3](./data.csv?type=scatter) fetches a per-type spec from a configured base URL and renders with d3.

Install

npm install @gridd/docusaurus-visuals-plugin

Configure

// docusaurus.config.ts
import { griddEmbed, griddInlineEmbed, chartEmbed, d3Embed } from "@gridd/docusaurus-visuals-plugin/remark";

const config = {
  plugins: ["@gridd/docusaurus-visuals-plugin"],
  customFields: {
    // Required: where your built embeddable.html is hosted.
    griddEmbedBaseUrl: "https://your-gridd-deploy.azurestaticapps.net/embeddable.html",
  },
  presets: [
    [
      "classic",
      {
        docs: {
          remarkPlugins: [
            [griddEmbed,       { styleSrc: "/style/style.gridd.json" }],
            [griddInlineEmbed, { styleSrc: "/style/style.gridd.json" }],
            chartEmbed,
            [d3Embed, { specBaseUrl: "/style/d3" }],
          ],
        },
      },
    ],
  ],
};

The Docusaurus plugin registers the React components (GriddEmbed, GriddInlineEmbed, Chart, D3Embed) via a swizzle of MDXComponents, so they don't need to be imported manually in MDX files.

Plugin options

| Plugin | Option | Purpose | | ------------------- | ------------- | --------------------------------------------------------------------------------------------- | | griddEmbed | styleSrc | Path to a common Gridd stylesheet JSON. Forwarded to the embed via gridd_style_uri. | | griddInlineEmbed | styleSrc | Same as above, applied to inline ```gridd``` blocks. | | d3Embed | specBaseUrl | Base URL where per-type spec files live; the component fetches ${specBaseUrl}/${type}.json. |

chartEmbed takes no options.

Markdown shorthand

Referenced Gridd embed

Load slide data from a pre-built JSON asset:

[$Gridd](./asset.json)

Renders as <GriddEmbed src="…" styleSrc="…" />. The JSON file must be a valid Gridd JSON exported from the editor.

Inline Gridd embed

Write the slide directly in the doc as a fenced gridd code block containing a simplified YAML format:

```gridd
cells: |
  |   | 0.5             | 1.5                      |
  |---|-----------------|--------------------------|
  | * | **Founder 1**   | Body text for row 1.     |
  | * | **Founder 2**   | Body text for row 2.     |

borders:
  - index: 1
    isVertical: false
    preset: level3

cellStyles:
  templates:
    Header:
      preset: Header
      weight: bold
      size: 16pt
      fontFamily: Arial
      color: "#FFFFFF"
      isInverted: true
      textAlign: left
      verticalAlign: middle
    Body:
      preset: Body
      weight: normal
      size: 12pt
      fontFamily: Arial
      color: "#333333"
      textAlign: left
      verticalAlign: middle

  "0,0": { template: Header }
  "0,1": { template: Body }
  "1,0": { template: Header }
  "1,1": { template: Body }
```

YAML format reference

The cells field is a markdown table (YAML literal block |):

• Header row — first cell is the row-weight corner (leave blank or *); remaining cells are column weights (0.5, 1.5, *, or s56 for a pixel-wide spacer).
• Data rows — first cell is the row weight; remaining cells are the content, with inline markdown (**bold**) and <br> for line breaks within a cell.

The cellStyles block supports:

| Key | Purpose | | --- | ------- | | templates | Named style objects merged into each cell via template: Name. | | global | Global style overrides applied to all cells, e.g. fontSizeAdd: -3. | | "row,col" | Per-cell style. References a template and adds overrides (icon, shape, etc.). |

The plugin converts this YAML to full Gridd JSON at build time (reversing the 8 simplification steps documented in the worldmap). The data is delivered to the embed via postMessage — no URL length limits apply.

When to use inline vs referenced

| | Inline ```gridd``` | Referenced [$Gridd] | |---|---|---| | Source lives in | the Markdown file | a separate .json file | | Editable in embeddable.html | yes (on localhost) | yes | | Changes require | editing the .md file | editing or re-exporting the .json | | Best for | documentation, examples, living slides | slides managed in the Gridd editor |

Charts and D3

| Shorthand | Component | | -------------------------------------------------- | -------------------------------------------------------- | | [$Chart](./data.csv) | <Chart src="…" /> (line) | | [$BarChart](./data.csv) | <Chart src="…" type="bar" /> | | [$AreaChart](./data.csv) | <Chart src="…" type="area" /> | | [$Chart](./data.csv?type=area&height=300) | <Chart src="…" type="area" height="300" /> | | [$D3](./data.csv?type=scatter) | <D3Embed dataSrc="…" type="scatter" specBaseUrl="…" /> |

Query-string params are forwarded as JSX attributes by name. Any <Chart>, <GriddEmbed>, <GriddInlineEmbed>, or <D3Embed> JSX element can also be written directly in MDX for finer control.

Cross-origin asset bridge (Gridd)

When the Gridd embed runs at a different origin than the docs page (typical for production deploys), browser CORS blocks the embed's direct fetch() of the asset URL.

• <GriddEmbed> registers a message listener that proxies fetches for its iframe via the parent's same-origin context, so any asset URL the docs page can reach, the embed can read.
• <GriddInlineEmbed> uses a postMessage handshake instead of a URL parameter to deliver slide data. The iframe sends a gridd-inline-request message on mount; the parent component replies with a gridd-inline-response containing the base64-encoded JSON. This avoids HTTP 431 errors from large query strings on production servers.

See the embed-side counterpart in your Gridd build for the matching gridd-proxy-fetch and gridd-inline-request message formats.

Using inline embeds on static HTML (without Docusaurus)

The packages/gridd-embed/gridd-embed.js standalone script provides the same gridd fenced block support for plain HTML pages — no build step needed. It scans for <pre><code class="language-gridd"> elements rendered by your static site generator and replaces them with Gridd iframes, using the same postMessage handshake.

<!-- Optional: YAML support (JSON blocks work without it) -->
<script src="https://cdn.jsdelivr.net/npm/js-yaml@4/dist/js-yaml.min.js"></script>

<script src="gridd-embed.js"
        data-gridd-base-url="https://your-gridd-deploy.azurestaticapps.net/embeddable.html"
        data-gridd-style-uri="/style/style.gridd.json"></script>

Or configure via globals set before the script loads:

<script>
  window.GRIDD_EMBED_BASE_URL = "https://your-gridd-deploy.azurestaticapps.net/embeddable.html";
  window.GRIDD_STYLE_URI = "/style/style.gridd.json";
</script>
<script src="gridd-embed.js"></script>

Adding new D3 diagram types

The D3Embed component dispatches on type to a renderer registry inside the bundled component. Out of the box only scatter is implemented. To add e.g. force, swizzle the D3Embed component, drop a force.json spec into the specBaseUrl folder, and add a force entry to the renderer registry consuming that spec.

Peer dependencies

Requires @docusaurus/core 3.x and React 18 or 19, both expected to be present in the consumer.