Skip to content

A remark plugin for turning d2 code blocks into diagrams in Markdown

License

Notifications You must be signed in to change notification settings

mech-a/remark-d2

Repository files navigation

remark-d2

License: MIT

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

remarkdemo.mp4

Features

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

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

becomes:

<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",
    },
  })

  .processSync(file);

gets you

Colorful Diagram

Try changing color modes and see!

Installation

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

npm install remark-d2

Usage

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/intro.md",
  value: readFileSync("docs/intro.md"),
});

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

console.log(output.toString());

Integrations

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

Configuration

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" }

Inspiration

remark-simple-plantuml

About

A remark plugin for turning d2 code blocks into diagrams in Markdown

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published