DEV Community: mrduguo

Slide Builder: RevealJS in YAML, with Prezi-style zoom

mrduguo — Sun, 05 Jul 2026 15:51:56 +0000

Slides have an odd status in engineering: we make them constantly, but we treat them as disposable. They rarely live in a repo. They rarely go through review. The diagram you spent twenty minutes aligning in Keynote is gone the moment the talk ends.

Dinghy's Slide Builder treats a slide like any other artifact: a folder of source files that compiles to a single deliverable.

What it is

A presentation builder layered on top of RevealJS, wired into the same Dinghy CLI you already have:

YAML DSL: recognized keys map to semantic blocks, and any other key becomes the matching HTML element, so you describe slides in a structured, indented form.
Markdown and HTML, auto-loaded: drop a .md or .html file in the slide folder and it becomes a section.
Self-contained HTML output: assets inlined, a single file you can share or host anywhere.
Live reload dev server: run dinghy slide start and edit-to-reload feedback.
Prezi-style zoom and pan: exclusive to Dinghy, covered below.

A YAML slide

The core idea is that a slide is a tree of HTML elements, and YAML is a tidy way to describe nested structure:

sections:
  - badge: Show Case
    title: Slide Builder
    subtitle: author RevealJS presentations in YAML
    ul:
      li:
        - YAML DSL maps keys to HTML elements
        - Self-contained HTML output
        - Live reload development server

Some keys are recognized aliases: badge becomes <div class="badge">, title becomes <h2 class="title">, subtitle becomes <p class="subtitle">. Any other key, such as p, h3, ul, or li, becomes that HTML element directly. Multi-file slides are just multiple YAML files in the same folder, picked up in filename order.

A Markdown slide

If you want to add a section quickly, plain Markdown works:

## Slide Builder

- YAML DSL maps keys to HTML elements
- Self-contained HTML output
- Live reload dev server

Markdown files become slides automatically. You can mix YAML, Markdown, and raw HTML in the same slide and use whichever fits each section.

The single-file output

Run dinghy slide build and you get one HTML file, with every image, font, and dependency inlined. There is nothing to host. You can drop it into a chat, open it offline, or email it. RevealJS rendering is intact, navigation works, and the speaker view works.

This matters for talks at venues with unreliable WiFi: your slide is a self-contained file that depends on nothing but a browser.

The Prezi-style feature

The one part that is exclusive to Dinghy is zoom-and-pan slides. You give an image and a set of regions by pixel coordinate, and the slide zooms into each region in turn instead of cutting to a new one:

- id: dinghy-proxy-project
  img: imgs/dinghy-proxy-project.png
  width: 1562
  height: 1398
  sections:
    - id: dinghy-proxy-title
      x1: 71
      y1: 842
      x2: 954
      y2: 1132
    - id: dinghy-proxy-ruby
      title: ❤️
      x1: 1052
      y1: 119
      x2: 1550
      y2: 293

The slide flies into each rectangle in turn. This is useful for architecture diagrams you want to walk through region by region without redrawing them five times. Under the hood it builds on RevealJS's data-auto-animate to morph between views, but the coordinate-based syntax is unique to Dinghy: in plain RevealJS you would have to calculate the CSS transforms by hand.

Why bother

The same reasons authoring in source pays off everywhere else:

The slide lives in the repo, gets reviewed, and gets diffed.
Change a shared section once, and every slide that includes it updates.
The output is one file, not a Keynote bundle, not a Google Slides URL, not a link that only works on the company VPN.

If you give more than a couple of talks a year, the cost of authoring in YAML is repaid by the sixth or seventh slide.

See it in action

The Introduction to Dinghy slide is built with the Slide Builder. It is a live example of the YAML DSL, the auto-loaded multi-file layout, and the Prezi-style zoom-and-pan described above. The source is on GitHub.

Site Builder: from one Markdown file to a deployed site in three commands

mrduguo — Sun, 05 Jul 2026 14:42:47 +0000

If you have ever tried to spin up a Docusaurus site, you know the routine: scaffold the project, install dependencies, write a config, pick a theme, get the navbar right, and only then can you start writing the actual docs.

Dinghy collapses all of that setup into a single command.

Minimal setup

mkdir -p src/pages
echo "# Welcome" > src/pages/INDEX.mdx
dinghy site start

That is all the setup there is. One folder, one file, one command, and you have live preview running at http://localhost:3000 with hot reload.

There is no package.json, no node_modules, and no Docusaurus config to write. The Dinghy engine ships a fully configured Docusaurus inside its Docker image and points it at your src/ folder.

What you get

The defaults are designed to work without any further setup:

src/pages/: standalone MDX pages (the homepage lives at INDEX.mdx).
src/docs/: docs section with sidebar navigation generated from the directory tree.
src/blog/ or blog/: blog section with date-prefixed posts. Both the root-level blog/ and src/blog/ are picked up; this site uses the root-level blog/.
src/css/custom.css: custom theme overrides, loaded automatically.
static/: assets, served as-is.

If a folder is present, it is used. If it is not, Dinghy leaves it alone.

Customizing

When the defaults are not enough, drop a docusaurus.config.yml in the site root. Dinghy intercepts a set of top-level keys such as docs, blog, theme, themeConfig, navbar, footer, and sidebars, and merges everything else straight into the underlying Docusaurus config:

title: My Project
navbar:
  title: My Project
  items:
    - label: Guides
      to: /guides/getting-started
      position: left

Set logo: false to drop the default logo. Set footer: false to drop the footer entirely. Anything Docusaurus supports, you can reach.

Deploying to S3

S3 is a built-in deploy target. Add it to your config:

deploy:
  s3Url: s3://my-bucket/path
  s3Region: us-east-1

Then:

dinghy site deploy

The deploy command is not a thin wrapper. It does the things you would otherwise do by hand:

Removes .html extensions so URLs look clean.
Gzip-compresses text files (HTML, JS, CSS, SVG, XML, TXT, JSON) before upload.
Sets cache-control headers that match the file type: public,max-age=2592000 (about 30 days) for content-hashed assets, and public,max-age=3600,must-revalidate (one hour) for mutable files.

If you have ever shipped a static site and found out months later that your HTML was being served with a one-year cache header, this is the kind of detail the deploy step handles for you.

The pattern

Dinghy's builders work the same way every time: sensible defaults that cover the common case, overrides for the rest, and a single command (start, build, deploy) for each step of the lifecycle.

Infrastructure as Code with OpenTofu/Terraform

mrduguo — Tue, 23 Jun 2026 20:40:42 +0000

The origin story explained why Dinghy renders TSX to Terraform. This post is the how, at two levels. First we create an EC2 instance by hand from the lowest-level pieces Dinghy gives you, one component per Terraform resource. Then we bundle those pieces into composite components and watch eight lines of TSX turn into a complete server stack: VPC, subnet, security group, IAM, and more.

Part 1: Basic service components

One component per Terraform resource

The foundation of Dinghy's AWS support is a set of basic service components. There is one component for every Terraform resource, generated directly from the provider schema:

Terraform resource	Dinghy component
`aws_instance`	`AwsInstance`
`aws_vpc`	`AwsVpc`
`aws_subnet`	`AwsSubnet`
`aws_security_group`	`AwsSecurityGroup`

The mapping is mechanical: the snake_case resource name becomes a Aws-prefixed PascalCase component, every argument becomes a prop, and the whole thing is type checked against the provider schema. There are around 245 AWS services covered this way, so if Terraform can describe it, there is a component for it.

These are deliberately thin. A basic component does not add opinions or defaults. It is a 1:1 typed wrapper around a single resource. That makes them the building blocks everything else is assembled from.

Building a server by hand

Here is a complete program that creates an EC2 instance, using nothing but a basic component:

import { Shape } from '@dinghy/base-components'
import { AwsProvider } from '@dinghy/tf-aws'
import { LocalBackend } from '@dinghy/tf-common'
import { AwsInstance } from '@dinghy/tf-aws/serviceEc2'

export default () => (
  <Shape _title='Server With Basic Building Blocks'>
    <AwsProvider>
      <Server />
      <LocalBackend />
    </AwsProvider>
  </Shape>
)

const Server = (props: any) => (
  <AwsInstance
    ami='ami-005e54dee72cc1d00'
    instance_type='t3.nano'
    _title='my-demo-server'
    {...props}
  />
)

Three pieces do the work:

AwsProvider configures the AWS provider (region and so on).
LocalBackend stores Terraform state on disk. In production you would swap this for an S3 backend, but local is perfect for a first run.
AwsInstance is the resource we actually want.

That is the whole point of a basic component. AwsInstance is a typed, 1:1 stand-in for the aws_instance resource: its props (ami, instance_type, and the rest) map straight onto the resource's arguments, with nothing added.

What renders out

Running this through Dinghy produces plain Terraform JSON:

{
  "resource": {
    "aws_instance": {
      "awsinstance_mydemoserver": {
        "ami": "ami-005e54dee72cc1d00",
        "instance_type": "t3.nano",
        "tags": {
          "Name": "my-demo-server",
          "iac:id": "awsinstance_mydemoserver"
        }
      }
    }
  }
}

The only thing in there you did not type is the tag block. iac:id is how Dinghy keeps a stable identity for each resource across renders, and Name comes from the _title. Everything else is a plain translation of the props you wrote. This is regular Terraform: you can read it, diff it, and apply it with the standard tooling.

Basic components give you complete control and a 1:1 map to Terraform, at the cost of writing every resource yourself. For a single instance that is fine. But a real server also needs a VPC, a subnet, an internet gateway, a security group, and an IAM role. Writing all of those by hand is a lot of repetitive work. That is where the second layer comes in.

Part 2: Composite components

Infrastructure in one tag

A single instance is small. Composite components pay off when the thing you want is made of a dozen resources that all have to reference each other correctly. A working EC2 server needs a VPC, a subnet, an internet gateway, a route, a security group, IAM, an AMI lookup, and the instance itself. Here is all of it:

import { AwsStack } from '@dinghy/tf-aws'
import { Ec2Servers } from '@dinghy/tf-aws/ec2'

export default () => (
  <AwsStack>
    <Ec2Servers />
  </AwsStack>
)

Two composites do all the work:

AwsStack replaced the scaffolding. In Part 1 we wrote Shape, AwsProvider, and LocalBackend ourselves. AwsStack folds the provider, the state backend, and an optional regional log bucket into one wrapper with sensible defaults. You only reach for the individual pieces when you want to override one.

Ec2Servers built the server. Eight lines of TSX render to 248 lines of Terraform JSON. It looks at what you asked for and creates whatever is missing:

Networking: aws_vpc, aws_subnet, aws_internet_gateway, a route, and the security group with ingress and egress rules.
Identity: an aws_iam_role, a policy attachment, and an aws_iam_instance_profile.
Image: a data.aws_ami lookup for the latest Amazon Linux 2023 (or Ubuntu) image.
The instance: aws_instance, plus an output with its id and public IP.

It also wires up AWS Session Manager by default, so you can connect to the instance without opening SSH or managing keys.

When the defaults are not what you want, you override through configuration rather than by dropping down to raw resources:

# dinghy.config.yml
servers:
  web1:
    instance_type: t4g.nano # arm64 instead of the t3.nano default
    linuxFlavor: ubuntu
  web2:
    instance_type: t3.small

That gives you two servers, on different architectures and distributions, still in the same eight lines of TSX.

The full example, with the source, the generated diagram, the complete 248-line Terraform, and the commands to deploy and connect, is at dinghy.dev/show-cases/ec2-servers.

A composite is just a component

The 248 lines might look surprising, so it is worth seeing that Ec2Servers is not a special language feature. It is an ordinary TSX component built from the basic building blocks of Part 1. The part that creates each instance, with the detail removed, looks like this:

function Ec2Server({ _server }: any) {
  const { awsAmi } = useAwsAmi()
  const { awsSubnet } = useAwsSubnet('public')
  const { instanceProfile } = useAwsIamInstanceProfile()
  return (
    <AwsInstance
      ami={awsAmi.id}
      subnet_id={awsSubnet.id}
      iam_instance_profile={instanceProfile.name}
      {..._server}
    />
  )
}

That is the same AwsInstance we wrote by hand in Part 1, now fed by the context lookup the origin story described. The composite renders the VPC, subnet, AMI lookup, and IAM role alongside the instance, and each useAws...() call reaches up the tree to find them, so you never pass references down through props by hand. The opinions and the boilerplate live in one place instead of being copied into every server you ever create.

It also creates only what you did not supply. Before rendering the instances, the composite inspects each server's props and decides which supporting resources to build on demand:

const createVpc = servers.some((s) => !s.subnet_id)
const referenceAmi = servers.some((s) => !s.ami)
const createInstanceProfile = servers.some((s) => !s.iam_instance_profile)

Pass your own iam_instance_profile and the composite uses it. Leave it out and it builds an IAM role and an aws_iam_instance_profile for you, with the SSM policy attached so dinghy aws connect can reach the instance. The VPC and the AMI lookup work the same way: supplied means reused, missing means created on demand.

Two levels, one model

That is the whole picture:

Basic components are the 1:1 building blocks. Complete control, more typing.
Composite components are ordinary components assembled from those blocks, with opinions and defaults built in. Less typing, fewer mistakes.

Neither replaces the other. A composite is built from basics, so you can always reach past it: nest a raw AwsVpcSecurityGroupIngressRule as a child of <Ec2Servers>, or swap an internal piece through the _components prop, when you need something the defaults do not cover. You start at the high level and drop down only where it matters.

Diagram as Code with draw.io

mrduguo — Mon, 25 May 2026 21:35:50 +0000

Architecture diagrams have a habit of going stale the moment you redraw them. The boxes stop matching the systems, the arrows stop matching the dependencies, and after a quarter or two the diagram has more in common with the vibe of the system than with the actual one.

Dinghy fixes that the same way Terraform fixes ad-hoc infrastructure changes: by treating the diagram as code.

The basic shape

Every Dinghy diagram is a tree of Shape components. Dependencies are part of the model, declared with _dependsOn / _dependsBy. Layout direction comes from _direction.

import { Shape } from '@dinghy/base-components'

export default () => (
  <Shape>
    Web App
    <Shape _dependsOn='Load Balancer'>Client</Shape>
    <Shape>
      Cloud
      <Shape _direction='vertical'>
        Public Subnet
        <Shape _dependsOn='Application'>Load Balancer</Shape>
        <Shape _dependsBy='Load Balancer'>Firewall</Shape>
      </Shape>
      <Shape _direction='vertical'>
        Private Subnet
        <Shape _dependsOn='Postgres'>Application</Shape>
        <Shape>Postgres</Shape>
      </Shape>
    </Shape>
  </Shape>
)

Render it and you get a draw.io page with all the right boxes, all the right arrows, and a layout that looks like the source code looks: a Web App on the outside, a Cloud nested inside, two subnets stacked vertically, all the dependency edges drawn for you:

Named shapes for readability

The plain Shape version does describe the diagram — every box is labelled, every dependency is there — but it is not much fun to read. Everything is a Shape with a name, and you have to read the strings to work out what is what. This is exactly the kind of thing React's named components were made for. Lift each role into its own component and the diagram code becomes easy to read:

const Client = (props: any) => <Shape _dependsOn='Load Balancer' {...props} />

export default () => (
  <WebApp>
    <Client />
    <Cloud>
      <PublicSubnet>
        <LoadBalancer />
        <Firewall />
      </PublicSubnet>
      <PrivateSubnet>
        <Application />
        <Postgres />
      </PrivateSubnet>
    </Cloud>
  </WebApp>
)

Same diagram, but now <Client /> carries its semantics in its name. The layout primitives are still there — they have just moved one layer down, where they belong.

Styled shapes with icons

The final pass is to drop in real AWS icons instead of generic boxes:

import * as awsGeneralResources from '@dinghy/diagrams/entitiesAwsGeneralResources'

const Client = (props: any) => (
  <awsGeneralResources.Client
    _dependsOn='Load Balancer'
    {...props}
  />
)

@dinghy/diagrams/entitiesAwsGeneralResources ships the official AWS resource icons, ready to be dropped into a tree. The TSX still reads exactly the same — only the rendered output changes from generic shapes to AWS-flavored ones.

A new way to build draw.io diagrams

Dinghy is not a new diagram software. The output of every example above is still a plain .drawio file: you can open it in the draw.io editor, tweak it by hand, share it with someone who has never heard of Dinghy, and it will behave exactly like any other draw.io diagram.

What Dinghy changes is the way you build the diagram. Instead of dragging shapes around in an editor and nudging them by a few pixels until the layout looks roughly right — only to have it drift again the next time someone edits it — you describe the shapes and their relationships in TSX, and Dinghy lays them out pixel-perfect every time. Same input, same output, no manual cleanup. Everything draw.io already gives you — the shape library, the rendering, the editing experience, the ecosystem of tools that read .drawio files — stays exactly where it is.

Learn more

Follow the Diagram as Code get-started guide to scaffold your first project and render your first .drawio file.
Browse the example diagrams to see what real Dinghy diagrams look like — from a handful of shapes up to full AWS architectures.

Where React for IaC came from

mrduguo — Sun, 17 May 2026 09:47:27 +0000

This is the first technical post in the Dinghy series, and it is the one I had to write before any of the others made sense. It is the origin story of the project — how a Terraform codebase that had grown beyond what copy-paste could maintain ended up being rendered out of TSX — and the core concept the rest of Dinghy is built on.

How I ended up here

Back in the day, I was maintaining a Terraform codebase across several environments. Most of the configuration was duplicated between them — the same resources, the same modules, repeated for every environment with only the inputs changing. Every change had to land in every environment. Every difference between them was either a deliberate choice or a bug waiting to happen.

Modules helped. For a while. Then the modules themselves became the maintenance burden — a layer of indirection that still couldn't express what I actually wanted to say.

HCL is HashiCorp Configuration Language. The keyword is configuration. It describes resources. It does not let you reason about them.

I wanted a real language.

The first move: CDKTF

CDKTF — Cloud Development Kit for Terraform — was the obvious next stop. Write infrastructure in TypeScript, render to Terraform JSON, deploy with the regular Terraform tooling. I tried it. It did what it said on the tin: real loops, real functions, real imports, real IDE support.

But two things kept nagging.

Construct boilerplate. CDKTF inherits AWS CDK's construct pattern: new Vpc(this, 'vpc', {...}), then new Subnet(this, 'subnet', { vpc, ... }). Every resource needs a parent scope and a unique id, hand-passed. It is faithful to AWS CDK, but it never stopped feeling like extra steps around the thing I actually wanted to write.

Cross-resource wiring. When two resources needed to talk to each other, I was still threading handles by hand. Pass the VPC into the subnet. Pass the subnet into the EC2. Pass the EC2 into the security group rule. The hierarchy in my head — VPC contains subnets contains instances — was nowhere visible in the source.

CDKTF had solved the programmable-language problem. It had not, for me, solved the expressing nesting problem.

The click: TSX nests the way infrastructure nests

When you draw a cloud architecture diagram, you naturally nest things inside containers — the VPC box wraps the subnet boxes; the subnet boxes wrap the instances. That nesting is how the infrastructure composes.

The moment that turned this into a project rather than a complaint was noticing that TSX is already nested in the same way. When you write:

<Vpc>
  <Subnet>
    <Ec2 />
  </Subnet>
</Vpc>

The source code shape matches the runtime shape. The thing you write looks like the thing you mean. No new X(parent, id, {...}). No explicit handle threading. The parent is right there — it is the JSX element containing you.

The next step was obvious. React looks like a tool for building web pages, but underneath, it is a general-purpose engine for building trees. The part that turns your TSX into HTML doesn't actually need to produce HTML — it can produce anything, as long as you tell it how. Tell it to produce Terraform JSON, and that is what you get.

Don't worry about React's complexity

If React's hooks, lifecycle, and state-management debates have put you off, you can relax. Dinghy uses almost none of that.

Dinghy renders once. You write the TSX, Dinghy walks the tree from top to bottom one time, writes the Terraform JSON, and stops. No reactivity. No re-renders. No state to manage. No lifecycle.

So none of the modern React you might have struggled with applies here:

~~useState~~ — no local state
~~useEffect~~ — no side effects or lifecycle
~~useMemo~~ — nothing to memoise

Dinghy only keeps the bits that make the nesting work:

TSX — the authoring syntax
The tree-walker that turns TSX into output
useContext — for letting a child component reach a surrounding parent (the bucket trick you will see in the next section)

Most of what React has accumulated for browser UI doesn't apply here, and you don't need to know it.

Context fixes the wiring problem

Here is the bit that finally felt right. With CDKTF I was threading a bucket handle down through props. With Dinghy:

const BucketVersioning = () => {
  const { s3Bucket } = useAwsS3Bucket()
  return (
    <AwsS3BucketVersioning
      bucket={s3Bucket.bucket}
      versioning_configuration={{ status: 'Enabled' }}
    />
  )
}

<AwsS3Bucket ...>
  <BucketVersioning />
</AwsS3Bucket>

BucketVersioning does not need to be told which bucket it is enabling versioning on. It asks the surrounding AwsS3Bucket via context. Drop it anywhere under a bucket and it Just Works.

That is the kind of composition HCL fundamentally cannot give you. CDKTF can do it, but only by passing the parent reference by hand.

Beyond Web

The other thing that fell out of choosing React: the output can be anything. React doesn't care whether the result is HTML, native mobile widgets, terminal UI, or Terraform JSON. Point it at a different kind of output, and it produces that.

React started as a web library, but it has long since moved beyond the web:

Web — the original
Native — iOS and Android apps
CLI — Ink, Claude Code, and similar tools render terminal interfaces with React-like trees
Infrastructure — Dinghy, rendering diagrams and Terraform

Same model, different output. That is why a single engine can sensibly cover diagrams and infrastructure under one roof — what the tree renders to is just a detail.

Introduction to Dinghy: a Swiss-army knife for everyday engineering

mrduguo — Tue, 12 May 2026 20:39:11 +0000

If you ship anything for a living — diagrams, infrastructure, docs, slide decks — you have probably noticed that each of those things lives in its own world, with its own toolchain, its own opinionated editor, and its own subtle ways to drift out of sync.

Dinghy is an open-source toolchain that puts all of them under one roof. One CLI. One install. One consistent way to describe what you want as code and let the tools deliver the final artwork.

What it is

A Swiss-army knife for engineers who like writing code more than clicking through dialogs:

Diagram as Code — render architecture diagrams to draw.io.
Infrastructure as Code — render OpenTofu / Terraform from React TSX.
Site Builder — author docs sites with Docusaurus, live-preview them, deploy to S3.
Slide Builder — author RevealJS presentations in YAML / Markdown / HTML, with Prezi-style zoom-and-pan as a Dinghy-exclusive bonus.

It is powered by Deno and Docker, so you do not need to babysit Node versions, Python virtualenvs, Terraform providers, or any of the rest of it.

From a DevOps engineer's bench

Dinghy was built by a DevOps engineer, so it is shaped to walk with your code across the whole software development lifecycle — from local development through to CI/CD — instead of stopping at the edge of one stage.

How it is shaped

Dinghy splits cleanly into a thin CLI and a fat engine that runs in Docker. The CLI is what you install on your machine; the engine is a versioned image that ships every dependency Dinghy needs.

curl -fsSL https://get.dinghy.dev/install.sh | sh

That single command gets you the CLI. From then on, everything Dinghy does happens inside the engine image — which means every machine on your team gets the exact same versions of Deno, Node, OpenTofu / Terraform, and every TF provider, pinned through a single .dinghyrc file.

DINGHY_ENGINE_VERSION=0.1...

One lock. Predictable versions. No more "it works on my laptop" — and no more two-year-old projects you can't rebuild because the dependencies have rotted away.

Who it's for

Anyone who needs to write code for any of this work — a diagram, a piece of infrastructure, a docs site or web app, a slide deck. You do not need to use them all, and you do not need to use them all the time. Reach for one when that is all you need; pull in a few when the work spans more than one.

If any of that sounds useful for what you are building, the rest of this series digs into each capability one post at a time (coming soon — links will go live as each post is published):

Where React for IaC came from — the origin of the Dinghy project and core concept.
Diagram as Code with draw.io — author architecture diagrams as TSX components.
Infrastructure as Code — 248 lines of Terraform from 8 lines of source.
Site Builder — from one Markdown file to a deployed site.
Slide Builder — RevealJS in YAML, with Prezi-style zoom.
Dinghy in the AI age — still relevant? How it works alongside AI.

Ready to set sail?

curl -fsSL https://get.dinghy.dev/install.sh | sh

Guides and examples are at https://dinghy.dev.