mdat-plugin-tldraw

Mdat plugin to embed tldraw diagrams in Markdown files.

Overview

This is a plugin for the mdat CLI tool, which is a simple Markdown templating system optimized for embedding dynamic content in repository readmes and the like.

This plugin makes it easy to embed tldraw diagrams as SVG images in your Markdown files.

The plugin automatically generates both "light" and "dark" SVG variations of a tldraw sketch, and emits a <picture> element per GitHub's guidelines to present the correctly themed image based on the viewer's preferences.

Generated assets are intelligently hashed to aide in cache busting. For locally referenced files, the image will only be regenerated when the content in the source file changes.

The rule accepts either a path to a local .tldr file, or remote tldraw URLs.

The implementation is based on @kitschpatrol/tldraw-cli, which depends on Puppeteer to generate the assets, so it can be a bit slow. Referencing local files instead of remote URLs is recommended for improved performance.

Getting started

Dependencies

We'll assume you have mdat installed either globally or in your local project.

Installation

Install the plugin as a development dependency:

pnpm add -D mdat-plugin-tldraw

Register the plugin in your mdat config file, e.g. mdat.config.ts:

import type { Config } from 'mdat'
import tldraw from 'mdat-plugin-tldraw'

export default {
  rules: {
    ...tldraw,
  },
} satisfies Config

Usage

Assuming you have a sketch.tldr file in the root of your project, you can embed it in your Markdown file this:

<!-- tldraw({ src: "./sketch.tldr" }) -->

Then run the mdat CLI command on your Markdown file to expand the rule and embed the diagram:

mdat

To generate:

<!-- tldraw({ src: "./sketch.tldr" }) -->

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="assets/sketch-63a3366c-dark.svg">
  <source media="(prefers-color-scheme: light)" srcset="assets/sketch-63a3366c-light.svg">
  <img alt="tldraw diagram" src="assets/sketch-63a3366c-light.svg">
</picture>

<!-- /tldraw -->

By default, the generated assets are saved to an ./assets folder adjacent the Markdown file.

You can customize this by passing a dest argument relative to the Markdown file, e.g.:

<!-- tldraw({ src: "./sketch.tldr", dest: "./sketches" }) -->

Example Output

Give:

<!-- tldraw({ src: "./test/assets/tldraw-sketch.tldr" }) -->

Receive:

Compatibility

This version of the plugin is only compatible with mdat 2.x.

Older mdat 1.x compatible versions remain available.

Maintainers

kitschpatrol

Contributing

Issues are welcome and appreciated.

Please open an issue to discuss changes before submitting a pull request. Unsolicited PRs (especially AI-generated ones) are unlikely to be merged.

This repository uses @kitschpatrol/shared-config (via its ksc CLI) for linting and formatting, plus MDAT for readme placeholder expansion.

License

MIT © Eric Mika