0.2.3 • Public • Published


License: MIT

A remark plugin that turns d2 code blocks into diagrams in Markdown files.


Fast resizing and titling: metadata tags like width, position, and title are compiled:

      ┎─────── abbrev. ───────┒
```d2 w=150px;position=center;a="test"


<img alt="test" position="center" width="150px" src="/d2/docs/features/0.svg" />
All accepted metadata tags & abbreviations
  • width, w
  • height, h
  • position, p
  • title, t
  • alt, a

Change default d2 compile settings and default image attributes easily

const output = await remark()
  .use(remarkD2, {
    defaultD2Opts: ["-t 101", "--dark-theme 200"],
    //            "Orange Creamsicle" on light mode,
    //               "Dark Mauve" on dark mode
    defaultImageAttrs: {
      title: "Wow, colors!",
      alt: "Colorful Diagram",
      width: "700px",


gets you

Colorful Diagram

Try changing color modes and see!


Ensure that you have d2 installed and accessible on your PATH. Then, install using your favorite package manager:

npm install remark-d2


In your unified or remark toolchain, you can include the plugin. Note that the VFile passed in must have a path.

import { remark } from "remark";
import remarkD2 from "remark-d2";
import { VFile } from "vfile";
import { readFileSync } from "node:fs";

const file = new VFile({
  path: "docs/",
  value: readFileSync("docs/"),

const output = await remark().use(remarkD2).processSync(file);



remark-d2 is compatible with Docusaurus out of the box. However, as Docusaurus does not currently support ES Modules, to install remark-d2 follow the workaround mentioned in the Docusaurus docs:

// in `docusaurus.config.js`

// wrap your config in a function:
async function createConfig() {
  // import the plugin here
  const d2 = (await import("remark-d2")).default;
  // return your config
  return {
    title: ...,
    tagline: ...,
    presets: [ // install here or in plugin config
        '@docusaurus/preset-classic', // or any other preset
          docs: {
            remarkPlugins; [d2], // works out of the box

// export the function (will be automatically called)
module.exports = createConfig


Options can be passed in as a parameter in .use. They should be in an Object form.

  • compilePath
    • Relative path where d2 diagrams are exported in respective folders
    • default: static/d2, compatible with Docusaurus
  • ext
    • File extension for d2 diagrams: currently only svg or png
      • Note that png is slower and does not support automatic light/dark mode
    • default: svg
  • linkPath
    • Path prepended to the relative file path in the image URL
      • Useful if your build system removes the parent folder reference assets/ or static/
    • default: /d2, compatible with Docusaurus
  • defaultD2Opts
    • Options passed to d2 CLI. See man d2 for more.
    • default: ["-t=100", "--dark-theme=200"]
  • htmlImage
    • If true, replace all code blocks with HTML <img /> tags instead of Markdown images
      • If a code block has metadata, regardless of htmlImage's value, it will be an HTML image
    • default: false
  • defaultImageAttrs
    • Default attributes for images
      • Only the keys title and alt apply to both Markdown and HTML images. All other attributes are only used if it is an HTML image.
    • default: { alt: "d2 diagram" }



Package Sidebar


npm i remark-d2

Weekly Downloads






Unpacked Size

13.1 kB

Total Files


Last publish


  • mech-a