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:

<!-- 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 -->

Maintainers

@kitschpatrol

Contributing

Issues and pull requests are welcome.

License

MIT © Eric Mika