DEV Community: Tosiiko

Every MDL behavior attribute for htmx and TypeScript

Tosiiko — Thu, 11 Jun 2026 21:46:16 +0000

MDL has two small behavior paths:

MDL behavior attributes -> htmx hx-* output
MDL event attributes    -> exported JavaScript or TypeScript handlers

That means the source can stay compact:

form@api(post /api/profile)@result(profileResult)@swap(replace)@trigger(submit)@loading(profileBusy):
  .input@id(profileName)@name(name)@required
  .btn-primary@type(submit)(Save)
  status@id(profileBusy):
    Saving.

With the htmx adapter enabled, MDL emits validated htmx attributes:

<form
  class="mdl-form"
  hx-post="/api/profile"
  hx-target="#profileResult"
  hx-swap="outerHTML"
  hx-trigger="submit"
  hx-indicator="#profileBusy">
</form>

And with configured JavaScript or TypeScript modules, event attributes call
exported functions by name:

card@id(plannerPanel)@mount(mountPlanner):
  .btn-primary@click(addTask)(Add task)

export function mountPlanner(element: HTMLElement) {
  element.dataset.ready = "true";
}

export function addTask(event: MouseEvent) {
  event.preventDefault();
}

Enable the htmx adapter

Configure htmx as the behavior adapter in mdl.json:

{
  "head_scripts": [
    "https://cdn.jsdelivr.net/npm/htmx.org@2.0.10/dist/htmx.min.js"
  ],
  "behavior": {
    "adapter": "htmx",
    "version": "2"
  }
}

MDL source should use MDL behavior attributes such as @api(...),
@result(...), and @swap(...). Raw @hx-post(...), @hx-target(...), and
other raw htmx attributes are not emitted.

htmx behavior attribute map

These are the MDL behavior attributes supported by the htmx adapter.

MDL attribute	htmx output	Example
`@api(get /api/search)`	`hx-get="/api/search"`	`get`, `post`, `put`, `patch`, `delete`
`@result(searchResults)`	`hx-target="#searchResults"`	Targets `this`, `id`, `#id`, or `.class`
`@swap(inner)`	`hx-swap="innerHTML"`	See swap values below
`@trigger(input)`	`hx-trigger="input"`	Uses a known trigger event
`@loading(searchBusy)`	`hx-indicator="#searchBusy"`	Also accepts `this` or `#id`
`@confirm(Save changes?)`	`hx-confirm="Save changes?"`	Plain text prompt, max 200 chars
`@include(csrfToken)`	`hx-include="#csrfToken"`	Also accepts `this` or `#id`
`@select(resultFragment)`	`hx-select="#resultFragment"`	Selects one response fragment
`@select-oob(toast)`	`hx-select-oob="#toast"`	Selects one out-of-band fragment
`@swap-oob(true)`	`hx-swap-oob="true"`	Also accepts known swap values
`@push(false)`	`hx-push-url="false"`	`true`, `false`, or safe root path
`@replace(/profile)`	`hx-replace-url="/profile"`	`true`, `false`, or safe root path
`@history(false)`	`hx-history="false"`	`true` or `false`
`@history-elt(true)`	`hx-history-elt="true"`	Emits only for `true`
`@boost(true)`	`hx-boost="true"`	Only on safe local links/forms
`@disabled(saveButton)`	`hx-disabled-elt="#saveButton"`	Also accepts `this` or `#id`
`@disinherit(target swap)`	`hx-disinherit="hx-target hx-swap"`	Allows known htmx attrs or `*`
`@encoding(multipart)`	`hx-encoding="multipart/form-data"`	Also supports urlencoded form encoding
`@inherit(trigger)`	`hx-inherit="hx-trigger"`	Allows known htmx attrs
`@params(name email)`	`hx-params="name,email"`	Explicit names or `none`
`@preserve(true)`	`hx-preserve="true"`	Requires a safe `@id(...)`
`@prompt(Security code?)`	`hx-prompt="Security code?"`	Plain text prompt, max 200 chars
`@request(timeout=5000)`	`hx-request="{"timeout":5000}"`	Timeout from `1` to `60000` ms
`@sync(profileForm:queue-last)`	`hx-sync="#profileForm:queue last"`	Coordinates concurrent requests
`@validate(true)`	`hx-validate="true"`	`true` or `false`

Supported `@api(...)` methods

get
post
put
patch
delete

@api(...) only emits same-origin-safe paths. External API URLs are not
emitted from this attribute.

Supported `@swap(...)` values

MDL gives short names to the htmx swap values:

MDL	htmx
`inner`	`innerHTML`
`inner-html`	`innerHTML`
`innerhtml`	`innerHTML`
`replace`	`outerHTML`
`outer`	`outerHTML`
`outer-html`	`outerHTML`
`outerhtml`	`outerHTML`
`append`	`beforeend`
`prepend`	`afterbegin`
`before`	`beforebegin`
`after`	`afterend`
`none`	`none`

@swap-oob(...) supports true plus the same known swap values. false is not
emitted for @swap-oob(...).

Supported `@trigger(...)` values

submit
click
change
input
load
revealed
intersect
keyup
keydown
focus
blur
mouseenter
mouseleave

MDL intentionally does not emit htmx trigger filters or JavaScript-like trigger
expressions from @trigger(...).

Supported `@encoding(...)` values

multipart
multipart/form-data
form
urlencoded
application/x-www-form-urlencoded

These normalize to either multipart/form-data or
application/x-www-form-urlencoded.

Supported `@sync(...)` strategies

drop
abort
replace
queue
queue-first
queue-last
queue-all

You can pass the strategy by itself:

form@sync(queue-last):

Or scope it to one explicit target:

form@sync(profileForm:queue-last):

Supported `@inherit(...)` and `@disinherit(...)` names

These attributes accept MDL names or htmx names. MDL normalizes them to htmx
attribute names.

target / result       -> hx-target
swap                  -> hx-swap
trigger               -> hx-trigger
indicator / loading   -> hx-indicator
confirm               -> hx-confirm
include               -> hx-include
select                -> hx-select
select-oob            -> hx-select-oob
swap-oob              -> hx-swap-oob
push / push-url       -> hx-push-url
replace / replace-url -> hx-replace-url
history               -> hx-history
history-elt           -> hx-history-elt
boost                 -> hx-boost
disabled / disabled-elt -> hx-disabled-elt
disinherit            -> hx-disinherit
encoding              -> hx-encoding
inherit               -> hx-inherit
params                -> hx-params
preserve              -> hx-preserve
prompt                -> hx-prompt
request               -> hx-request
sync                  -> hx-sync
validate              -> hx-validate
get                   -> hx-get
post                  -> hx-post
put                   -> hx-put
patch                 -> hx-patch
delete                -> hx-delete

@disinherit(*) is also supported. @inherit(*) is not.

Configure TypeScript handlers

MDL scripts can point at JavaScript or TypeScript module entries:

{
  "scripts": [
    "scripts/app.ts"
  ]
}

During mdl build, MDL compiles local .ts module scripts to browser-ready
JavaScript:

scripts/app.ts -> dist/scripts/app.js

The generated HTML imports the JavaScript URL:

<script type="module">
import * as mdlModule0 from "./scripts/app.js";
</script>

During mdl serve, the browser still asks for ./scripts/app.js, and the dev
server serves JavaScript compiled from scripts/app.ts.

Configured TypeScript entries can import local TypeScript trees:

scripts/app.ts
scripts/state/store.ts
scripts/dom/render.ts
scripts/utils/format.ts

MDL preserves the folder tree in output:

dist/scripts/app.js
dist/scripts/state/store.js
dist/scripts/dom/render.js
dist/scripts/utils/format.js

Local TypeScript imports may use .ts, omit the extension, or use the
browser-facing .js extension:

import { snapshot } from "./state/store.ts";
import { renderTaskList } from "./dom/render.js";
import { formatCount } from "./utils/format";
import type { Task } from "./state/model.ts";

MDL does not create package.json, node_modules, or tsconfig.json for this.
It is transpile-only behavior support, not a bundler or project type checker.

Inline TypeScript blocks are not supported yet:

script ts:
  // not supported yet

Use inline JavaScript:

script js:
  document.body.dataset.ready = "true"

Or an external configured .ts module.

TypeScript event attributes

Event attributes compile to data-mdl-on-* markers, and MDL's generated module
runtime calls exported handlers by name.

form@submit(createTaskFromForm):
  .input@input(updateDraftPreview)
  .btn-primary@click(saveTask)(Save)

canvas@id(scene)@mount(drawScene):

<form class="mdl-form" data-mdl-on-submit="createTaskFromForm">
  <input class="mdl-input" data-mdl-on-input="updateDraftPreview">
  <button class="mdl-btn-primary" data-mdl-on-click="saveTask">Save</button>
</form>
<canvas class="mdl-canvas" id="scene" data-mdl-on-mount="drawScene"></canvas>

@mount(handler) is not a browser event. It runs once after configured modules
are imported and receives the mounted element.

All other handlers receive the browser event.

Complete event alias list

These event attributes can be handled from JavaScript or TypeScript modules:

@click              @dblclick           @auxclick          @contextmenu
@command
@submit             @reset              @formdata          @beforeinput
@input              @change             @invalid           @search
@select
@compositionstart   @compositionupdate  @compositionend
@focus              @blur               @focusin           @focusout
@keydown            @keypress           @keyup
@mousedown          @mouseup            @mousemove         @mouseover
@mouseout           @mouseenter         @mouseleave
@pointerdown        @pointerup          @pointermove       @pointerover
@pointerout         @pointerenter       @pointerleave      @pointercancel
@pointerrawupdate   @gotpointercapture  @lostpointercapture
@touchstart         @touchmove          @touchend          @touchcancel
@wheel              @scroll             @scrollend
@load               @error              @abort             @resize
@canplay            @canplaythrough     @play              @playing
@pause              @ended              @durationchange    @emptied
@loadeddata         @loadedmetadata     @loadstart         @progress
@ratechange         @seeked             @seeking           @stalled
@suspend            @timeupdate         @volumechange      @waiting
@dragstart          @drag               @dragenter         @dragover
@dragleave          @drop               @dragend
@copy               @cut                @paste
@cuechange          @slotchange
@toggle             @beforetoggle       @beforematch       @close
@cancel             @contextlost        @contextrestored
@securitypolicyviolation
@fullscreenchange   @fullscreenerror
@animationstart     @animationiteration @animationend      @animationcancel
@transitionrun      @transitionstart    @transitioncancel  @transitionend

TypeScript handler example

form@id(taskForm)@submit(createTaskFromForm):
  .input@id(taskTitle)@name(title)@type(text)@required@input(updateDraftPreview)
  .btn-primary@type(submit)(Add task)

card@id(plannerPanel)@mount(mountPlanner):
  status@id(boardStatus)@aria-live(polite):
    Waiting for TypeScript.

export function mountPlanner(element: HTMLElement) {
  element.dataset.ready = "true";
}

export function createTaskFromForm(event: SubmitEvent) {
  event.preventDefault();

  const form = event.currentTarget;
  if (!(form instanceof HTMLFormElement)) return;

  const data = new FormData(form);
  const title = String(data.get("title") ?? "").trim();
  if (!title) return;

  // Update app state, then render.
}

export function updateDraftPreview(event: Event) {
  const input = event.currentTarget;
  if (!(input instanceof HTMLInputElement)) return;

  const preview = document.querySelector("#draftPreview");
  if (preview) preview.textContent = input.value;
}

General MDL attribute rules

Normal HTML attributes are still direct:

.input@id(email)@name(email)@type(email)@required@autocomplete(email)

That emits:

<input class="mdl-input" id="email" name="email" type="email" required autocomplete="email">

The core rules are:

@attr(value) emits attr="value".
@attr emits a boolean attribute.
@class(...) appends author classes after the generated mdl-* class.
Raw browser event attributes such as @onclick(...) are not emitted.
Raw htmx attributes such as @hx-post(...) are not emitted.
Inline @style(...) and iframe @srcdoc(...) are not emitted.
URL attributes are filtered to safe URL shapes.

The reason is boring in the best way: MDL keeps authoring short, but the output
should remain inspectable and hard to accidentally turn into a script sink.

Try the examples

The htmx example app:

node examples/htmx/server.mjs
target/debug/mdl serve examples/htmx

Open:

http://127.0.0.1:4010

The TypeScript example:

cd examples/typescript
../../bin/mdl serve

Open:

http://127.0.0.1:3996

MDL 0.1.9: optional TypeScript behavior scripts without a TypeScript project setup

Tosiiko — Thu, 11 Jun 2026 20:19:47 +0000

MDL 0.1.9 adds optional external TypeScript behavior scripts.

The important word is optional.

MDL is still:

.mdl  -> structure and content
.css  -> layout and design
.js   -> optional behavior
HTML  -> compiler output

This release does not turn MDL into a JavaScript-app workflow. It does not make
TypeScript a requirement for normal MDL sites. It simply means that if you want
typed behavior modules, MDL can compile local .ts files for the browser during
build and serve.

What changed

Before this release, an MDL project config could include JavaScript module
scripts:

{
  "scripts": [
    "scripts/app.js"
  ]
}

mdl build copied those files unchanged, and generated HTML imported them as
module scripts.

In 0.1.9, the same scripts array can also point at a local TypeScript entry:

{
  "scripts": [
    "scripts/app.ts"
  ]
}

During mdl build, MDL transpiles that entry to JavaScript:

scripts/app.ts -> dist/scripts/app.js

The generated document imports the browser-ready JavaScript URL:

<script type="module">
import * as mdlModule0 from "./scripts/app.js";
</script>

During mdl serve, the page still imports ./scripts/app.js. The dev server
serves that compiled JavaScript from the configured TypeScript source, so the
development URL matches the production URL.

TypeScript trees are supported

The first pass is not limited to a single file. A configured TypeScript entry
can import other local TypeScript modules:

scripts/app.ts
scripts/state/store.ts
scripts/state/model.ts
scripts/dom/forms.ts
scripts/dom/render.ts
scripts/utils/id.ts

MDL follows the local static import/export graph, preserves the folder tree, and
emits matching JavaScript modules:

dist/scripts/app.js
dist/scripts/state/store.js
dist/scripts/state/model.js
dist/scripts/dom/forms.js
dist/scripts/dom/render.js
dist/scripts/utils/id.js

Local TypeScript imports may use .ts, omit the extension, or use the
browser-facing .js extension. MDL rewrites local TypeScript module specifiers
to emitted .js URLs.

For example, this is valid in source:

import { snapshot } from "./state/store.ts";
import { renderTaskList } from "./dom/render.js";
import { byId } from "./dom/query";
import type { TaskFilter } from "./state/model.ts";

The emitted JavaScript uses browser-safe JavaScript module URLs for the local
TypeScript files.

Type-only imports stay type-only. They do not become runtime dependencies.

What MDL does not do

This is transpile-only support for behavior modules.

MDL does not:

scaffold package.json
create node_modules
create tsconfig.json
require users to install TypeScript
require deployed sites to carry TypeScript
bundle npm packages
type-check the project yet

Bare package imports and external URLs are left alone. MDL is not trying to be
a bundler in this release.

The TypeScript parser/transpiler lives inside MDL tooling, so a site can use a
configured .ts behavior module without becoming a TypeScript project.

Inline scripts stay JavaScript for now

Inline JavaScript blocks keep working:

script js:
  const form = document.querySelector("#loginForm")
  form?.classList.add("ready")

Inline TypeScript is still unsupported:

script ts:
  // not supported yet

For TypeScript, use an external configured module:

{
  "scripts": [
    "scripts/app.ts"
  ]
}

Event bindings still work the same way

Full-document MDL output imports configured modules and binds exported functions
to MDL behavior attributes:

form@id(taskForm)@submit(createTaskFromForm):
  .input@id(taskTitle)@name(title)@type(text)@input(updateDraftPreview)
  .btn-primary@type(submit)(Add task)

card@id(plannerPanel)@mount(mountPlanner):
  status@id(boardStatus):
    Waiting for the TypeScript module tree.

Your TypeScript module exports the handlers:

export function mountPlanner(element: HTMLElement) {
  element.dataset.ready = "true";
  refresh("Planner mounted from compiled TypeScript.");
}

export function createTaskFromForm(event: SubmitEvent) {
  event.preventDefault();
  // read the form, update state, re-render
}

export function updateDraftPreview(event: Event) {
  // update live preview while the user types
}

MDL handles the wiring. The browser receives JavaScript modules.

New example: `examples/typescript`

This release adds a more advanced TypeScript example:

examples/typescript

It is a small typed task planner with:

a configured scripts/app.ts entry
nested state, DOM, and utility modules
import type usage
imports that use .ts, .js, and extensionless specifiers
@mount, @submit, @input, @change, and @click handlers
dashboard metrics
task filters
form parsing
toast updates
generated dist/scripts/*.js output

Run it:

cd examples/typescript
../../bin/mdl serve

Open:

http://127.0.0.1:3996

Build it:

../../bin/mdl build

The example intentionally has no package.json, no node_modules, and no
tsconfig.json.

Why this shape?

I want MDL to keep a narrow architecture:

MDL source + CSS + optional behavior scripts -> static browser output

Some pages only need HTML and CSS. Some need a little inline JavaScript. Some
need external JavaScript modules. And some behavior is easier to maintain with
TypeScript types.

0.1.9 supports that last case without changing the default model.

The output is still plain browser assets. The project is still inspectable. The
site is still deployable as static files.

Try MDL

Install locally in a project:

mkdir my-mdl-site
cd my-mdl-site
npm install @tosiiko/mdl
npm exec -- mdl init
source bin/activate
mdl serve

Or install globally:

npm install -g @tosiiko/mdl
mdl new my-mdl-site
cd my-mdl-site
mdl serve

Useful commands:

mdl check
mdl format --check
mdl build
mdl serve

Links

Website: https://getmdl.site
Repository: https://github.com/tosiiko/mdl-code
npm package: https://www.npmjs.com/package/@tosiiko/mdl
TypeScript example: examples/typescript
Script spec: docs/spec/SCRIPTS.md

MDL is still early, but 0.1.9 makes optional behavior code easier to grow:
JavaScript still works exactly as before, TypeScript can live in local external
modules, and deployed sites only need the compiled JavaScript.

MDL 0.1.8: htmx examples, safer npm binaries, and portable static builds

Tosiiko — Sat, 06 Jun 2026 11:53:19 +0000

MDL 0.1.8 is a release focused on two things:

Making hypermedia workflows easier to see and copy.
Making the npm CLI package easier to inspect and trust.

MDL is a small authoring language for building clean HTML without writing raw
HTML by hand. You write .mdl files, regular CSS, and optional JavaScript; the
CLI checks, builds, and serves the project.

.mdl  -> structure and content
.css  -> layout and design
HTML  -> compiler output

New: Complete htmx Example App

This release adds a complete htmx example under:

examples/htmx

The app demonstrates MDL behavior attributes compiled through the htmx
adapter. Instead of writing raw hx-* attributes in MDL source, you describe
the intent:

form@api(get /api/search)@result(searchResults)@swap(inner)@trigger(input)@loading(searchBusy):
  field:
    label@for(searchQuery):
      Search cookbook entries
    .input@id(searchQuery)@name(q)@type(search)@placeholder(Type card, form, swap, or history)
  status@id(searchBusy)@class(indicator):
    Searching.

With the htmx adapter enabled, MDL emits the corresponding hx-* output:

<form
  class="mdl-form"
  hx-get="/api/search"
  hx-target="#searchResults"
  hx-swap="innerHTML"
  hx-trigger="input"
  hx-indicator="#searchBusy">
</form>

The example app includes:

live search
todo list swaps
cart updates
profile form validation
out-of-band toast updates
request indicators
disabled submit buttons
parameter filtering
request timeouts
sync behavior
prompted requests
preserved islands
boosted safe forms

Run the API server:

node examples/htmx/server.mjs

In another terminal:

target/debug/mdl serve examples/htmx

Then open:

http://127.0.0.1:4010

The example uses htmx 2.0.10 from a pinned CDN URL in mdl.json, and you can
vendor that script locally if you want an offline demo.

Behavior Adapters

MDL now has a clearer adapter story:

{
  "behavior": {
    "adapter": "htmx",
    "version": "2"
  }
}

Supported behavior adapters are:

static: normal HTML behavior where possible.
mdl: data-mdl-api-* attributes for future MDL runtimes.
htmx: validated hx-* output for htmx v2.

The important bit is that MDL source stays framework-neutral. You write
attributes such as:

@api(post /api/profile)
@result(profileResult)
@swap(replace)
@trigger(submit)
@loading(profileBusy)
@select-oob(toast)
@request(timeout=5000)
@sync(profileForm:queue-last)
@validate(true)

The adapter decides how that intent becomes HTML.

Safer npm Package

The npm package is also hardened in this release.

@tosiiko/mdl ships a small Node launcher and prebuilt Rust binaries for
supported platforms. That is convenient, but native binaries deserve a clear
audit trail.

0.1.8 adds:

SECURITY.md in the npm package
BINARY-PROVENANCE.md in the npm package
SHASUMS256.txt in the staged public package
runtime checksum verification before executing the selected binary
explicit shell: false process spawning in the launcher
provenance-enabled GitHub publishing with npm publish --provenance

The package still has:

no runtime npm dependencies
no npm lifecycle or install scripts
no install-time binary downloads
no runtime binary downloads

The launcher selects a binary from vendor/<platform>/, verifies its SHA-256
checksum when SHASUMS256.txt is present, and only then starts the CLI.

Portable Static Builds

This release also includes routing.links in mdl.json.

Use root links when deploying from a site root:

{
  "routing": {
    "links": "root"
  }
}

Use relative links when publishing dist/ under a subfolder or opening the
generated files directly:

{
  "routing": {
    "links": "relative"
  }
}

Relative mode rewrites local page and asset links so the output is easier to
move between static hosts.

Try MDL

Install locally in a project:

mkdir my-mdl-site
cd my-mdl-site
npm install @tosiiko/mdl
npm exec -- mdl init
source bin/activate
mdl serve

Or install globally:

npm install -g @tosiiko/mdl
mdl new my-mdl-site
cd my-mdl-site
mdl serve

Useful commands:

mdl check
mdl format --check
mdl build
mdl serve

Links

Website: https://getmdl.site
Repository: https://github.com/tosiiko/mdl-code
npm package: https://www.npmjs.com/package/@tosiiko/mdl
htmx examples: examples/htmx

MDL is still early, but 0.1.8 makes the project much easier to evaluate: you
can inspect the generated HTML, run a real htmx example, check the package
contents, and build static output that fits more hosting setups.

# Next MDL Update: Security-First Adapters and HTMX Support

Tosiiko — Sat, 06 Jun 2026 09:35:46 +0000

In the last update, I introduced MDL as an HTML-first language for building websites and apps with less noise.

This update is about the next layer: adapters.

The goal is simple:

MDL source should describe intent. Adapters decide how that intent becomes deployable HTML.

Why adapters?

I don’t want MDL to become locked into one frontend framework.

Instead, the same MDL structure should be able to target different deployment styles:

static HTML
MDL-native runtime attributes
HTMX
future template or framework adapters

So this:

form@api(post /api/login)@result(loginResult)@swap(replace):
  .input@type(email)@required
  .btn-primary@type(submit)(Sign in)

  status@id(loginResult):
    Waiting.

Can become plain HTML:

html

<form method="post" action="/api/login">

Or HTMX:

html

<form hx-post="/api/login" hx-target="#loginResult" hx-swap="outerHTML">

Security before convenienceThe important part is that MDL does not pass behavior attributes through blindly.
Raw HTMX attributes like this are blocked:

mdl

form@hx-post(/api/login):

Instead, MDL uses intent-based attributes:

mdl

form@api(post /api/login):

Then the adapter validates and translates it.
Current safety rules include:
external api(...) URLs are rejected
raw @hx-* attributes are blocked
raw browser events like onclick(...) are blocked
unsafe URL schemes like javascript: are blocked
broad form inclusion like @params() is blocked
@inherit() is blocked
@disinherit(*) is allowed because disabling inherited behavior is safer
That means MDL can support HTMX without making MDL source depend directly on HTMX’s full raw surface area.
New HTMX adapter attributesThe HTMX v2 adapter now supports more behavior attributes:

mdl

@select-oob(...)
@swap-oob(...)
@disabled(...)
@disinherit(...)
@encoding(...)
@history-elt(...)
@inherit(...)
@params(...)
@preserve(...)
@prompt(...)
@replace(...)
@request(...)
@sync(...)
@validate(...)

Example:

mdl

form@api(post /api/profile)@result(profileResult)@swap(replace)@params(email csrfToken)@disabled(saveButton):
  .input@name(email):
  .input@name(csrfToken):
  .btn-primary@id(saveButton)@type(submit)(Save)

  status@id(profileResult):
    Waiting.

With the HTMX adapter, MDL can emit:

html

<form
  hx-post="/api/profile"
  hx-target="#profileResult"
  hx-swap="outerHTML"
  hx-params="email,csrfToken"
  hx-disabled-elt="#saveButton">

Notice that @params(email csrfToken) is explicit. MDL does not allow @params(*), because accidentally sending extra form fields is exactly the kind of thing a language layer should help prevent.

I Built MDL: A Small Language for Writing Static Websites as Readable Outlines

Tosiiko — Mon, 01 Jun 2026 18:10:50 +0000

HTML is an excellent output format.

As an authoring format, though, it can become noisy when you're building simple documentation sites, landing pages, examples, or other static content.

I wanted something that let me write pages as readable outlines while still producing normal HTML at build time.

So I built MDL.

MDL is a small authoring language that compiles to clean static HTML.

It does not replace HTML, CSS, or JavaScript.

Instead, it sits one step above them and lets you write page structure in a format that is easier to scan and maintain.

What MDL Looks Like

A simple MDL page might look like this:

page:
  hero:
    .badge(New)
    # Build clean static sites

    Write readable page structure,
    then compile to HTML.

    actions:
      .href@href(/docs.html)@class(primary)
      (Read the docs)

  section:
    ## Why MDL?

    Keep content readable.
    Keep styling in CSS.
    Add JavaScript only when behavior belongs.

And it compiles to ordinary HTML:

<main class="mdl-page">
  <div class="mdl-hero">
    <span class="mdl-badge">New</span>
    <h1>Build clean static sites</h1>
  </div>
</main>

The output is intentionally boring.

That is the goal.

No runtime.
No framework lock-in.
No custom browser behavior.

Just static HTML.

Why I Built It

I kept finding myself wanting a format that felt closer to writing a structured note than writing a template.

For many sites I don't need:

Component systems
Hydration
Build-time JavaScript frameworks
Large configuration layers

I just want to describe the page structure clearly and generate predictable HTML.

MDL is my attempt at that.

The Browser Platform Stays Visible

One thing that mattered to me from the start:

CSS is still CSS
JavaScript is still JavaScript
HTML is still the final artifact

MDL is only the authoring layer.

You can inspect the generated pages and immediately understand what is happening.

Getting Started

Install from npm:

mkdir my-mdl-site
cd my-mdl-site

npm install @tosiiko/mdl

npm exec -- mdl init

source bin/activate

mdl serve

Then open:

http://127.0.0.1:3999

CLI Commands

mdl init
mdl new my-site
mdl check
mdl format
mdl build
mdl serve

Recent Improvements

Current release: 0.1.7

Some highlights:

Public documentation site is now live
Improved static hosting support
Routing control via mdl.json
Better package and editor metadata alignment
Expanded documentation
Deployment guidance and examples

Example routing configuration:

{
  "routing": {
    "links": "relative"
  }
}

This makes generated sites work cleanly when hosted under subfolders or served directly as static files.

For root-domain hosting:

{
  "routing": {
    "links": "root"
  }
}

Where I Think MDL Fits

MDL is especially useful for:

Documentation sites
Product pages
Landing pages
Project websites
Examples and demos
Small static sites

If you're already happy writing HTML directly, that's great.

If you've ever wished your page source looked more like an outline and less like markup, MDL might be interesting.

Feedback Welcome

The project is still early and I'm actively improving:

Documentation
Editor support
Templates
Diagnostics
Real-world examples

I'd love feedback from people who enjoy static sites, small tools, Markdown-style authoring, and clean HTML.

Documentation:

Links

Documentation: https://getmdl.site
npm package: https://www.npmjs.com/package/@tosiiko/mdl
GitHub: https://github.com/tosiiko/mdl-code

Package:

npm install @tosiiko/mdl

Questions, criticism, feature requests, and ideas are all welcome.

What's coming in MDL 0.1.3 — source maps, metadata, diagnostics, and more

Tosiiko — Sun, 31 May 2026 18:55:26 +0000

I've been building MDL — a tiny authoring language that compiles to clean HTML. If you haven't seen it yet:

page:
  hero:
    ## Sign in
    Welcome back.

  form@id(loginForm)@submit(handleLogin):
    field:
      label:
        Email
      .input@type(email)@id(email)@required

    actions:
      .btn-primary@id(loginBtn)(Sign in)
      .btn-ghost@click(handleForgot)(Forgot password?)

Compiles to clean, semantic HTML. No angle brackets written by hand. CSS owns all layout. JS handles all logic.

Install: npm install -g @tosiiko/mdl

What's already shipped in 0.1.x

Before getting into what's coming — here's what's already working:

Indentation-based sections that compile to semantic HTML (page: → <main>, nav: → <nav>, form: → <form>)
Full CommonMark Markdown inside every section — headings, lists, tables, code blocks, blockquotes
Dot inline elements — .badge(text), .btn-primary(text), .input@type(email)
Attributes — @id(value), @required, @placeholder(text), @submit(fn), @click(fn)
CSS bundling — multiple CSS files merged into one app.css
JavaScript event wiring — @submit(handleLogin) compiles to a proper addEventListener
Live reload dev server — mdl serve at localhost:3999
Multi-page projects via mdl.json
mdl init and mdl new — scaffold a full project in one command
mdl check and mdl format — lint and auto-format
VS Code extension with syntax highlighting — already on the marketplace
Prebuilt Rust binary distributed via npm — no Rust toolchain needed

That's 0.1. Here's what's coming next.

Source maps

Every compiled HTML page will write a JSON sidecar map:

pages/login.mdl  →  dist/login.html
                 →  dist/login.html.mdlmap.json

The map links every generated HTML element back to the MDL source line that produced it:

{
  "version": 1,
  "source": "pages/login.mdl",
  "output": "login.html",
  "mappings": [
    {
      "generated": { "line": 12, "column": 1, "end_line": 31, "end_column": 8 },
      "source": { "line": 6, "column": 3, "end_line": 6, "end_column": 39 },
      "kind": "section",
      "name": "form"
    }
  ]
}

This unlocks editor navigation, error overlays with exact MDL line and column, and eventually go-to-source from generated HTML back to the .mdl file that produced it — the same way browser source maps let you debug TypeScript instead of compiled JS.

A project-level dist/mdl-manifest.json links every route to its source and source map:

{
  "route": "/login",
  "source": "login.mdl",
  "output": "login.html",
  "source_map": "login.html.mdlmap.json"
}

Document metadata

Right now metadata lives in mdl.json. The next release formalises and extends this with a complete metadata system:

{
  "lang": "en",
  "title": "My Site",
  "description": "A small MDL site.",
  "canonical": "https://example.com/",
  "favicon": "assets/favicon.svg",
  "social": {
    "enabled": true,
    "image": "assets/social-card.png",
    "twitter_site": "@mysite"
  }
}

The social preset derives Open Graph and Twitter card tags automatically from title, description, and canonical. One config, full social sharing coverage:

<meta property="og:title" content="My Site">
<meta property="og:description" content="A small MDL site.">
<meta property="og:image" content="assets/social-card.png">
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:site" content="@mysite">

mdl check validates all local file references — favicon, social image, manifest links — at build time, not when a user finds a broken image in production.

Better diagnostics

mdl check is getting significantly smarter. The next release adds:

Accessibility checks:

Missing alt on images
Missing title on iframes
Duplicate IDs
Unlabeled form controls
Invalid or empty aria-* attributes
Missing ARIA references
Landmark ordering issues

Form checks:

Label and input pairing mistakes
Missing label targets
Ungrouped radio buttons
Missing autocomplete hints

Asset checks:

Broken .link() and .href() targets
Missing local images and media files
Recursive CSS url() and @import validation
Font file references

Machine-readable output:

mdl check --json

Outputs structured diagnostics with 1-based line and column ranges — ready for editor integrations, CI pipelines, and language server consumers.

Multi-app workspaces

One install, multiple apps:

mdl init --app admin --port 4001
mdl serve apps/admin

Each app owns its own mdl.json, pages, CSS, and scripts. They share the same MDL install and environment. Useful for projects with a public site and a separate admin panel, or a marketing page and a docs site.

Advanced browser primitives

The next release adds first-class MDL sections for:

canvas:      →  <canvas>   WebGL, charts, custom drawing
frame:       →  <iframe>   embedded content
picture:     →  <picture>  responsive images
progress:    →  <progress> loading bars
meter:       →  <meter>    scalar measurements
template:    →  <template> inert DOM templates
slot:        →  <slot>     web component slots
island:      →  <div>      hydrated JS island host
component:   →  <div>      custom component host

With @mount(handler) wiring for JS initialisation:

canvas@id(scene)@mount(drawScene):

Compiles to a <canvas> that calls drawScene() from your configured scripts on mount.

What I'm building toward

MDL's goal is simple: you should be able to build a complete, production-quality web page without writing a single HTML tag. Structure in .mdl. Design in .css. Logic in .js. The compiler handles everything else.

The next release gets closer to that by making the tooling smarter — better errors, better source maps, better metadata, better workspace support.

Try it now

npm install -g @tosiiko/mdl
mdl new my-site
cd my-site
mdl serve

npm — https://www.npmjs.com/package/@tosiiko/mdl/v/0.1.2
VS Code — https://marketplace.visualstudio.com/items?itemName=MDLLanguageSupport.mdl-language
GitHub — https://github.com/tosiiko/mdl-code

Would love to hear what you think — and what you'd want to see in MDL before you'd use it on a real project.

npm i @tosiiko/mdl

Tosiiko — Sat, 30 May 2026 10:44:07 +0000

The parser is written in Rust using pulldown-cmark for Markdown. It ships as a prebuilt binary via npm so no Rust toolchain is needed.

npm: https://www.npmjs.com/package/@tosiiko/mdl/v/0.1.2
VS Code: https://marketplace.visualstudio.com/items?itemName=MDLLanguageSupport.mdl-language
GitHub: https://github.com/tosiiko/mdl-code

I built MDL — a tiny authoring language so you never write raw HTML again

Tosiiko — Sat, 30 May 2026 10:35:39 +0000

The problem

Every web project starts the same way. You open a blank file and start typing angle brackets.

HTML is fine. But writing it by hand is noisy, repetitive, and forces you to think about tags instead of content.

What I built

MDL (Markdown Language) is a tiny authoring language that compiles to clean, semantic HTML.

The idea is three rules:

.mdl files handle structure and content
.css files handle layout and design
.js files handle logic

You never write a single HTML tag.

What it looks like

page:
  hero:
    ## Sign in
    Welcome back.

  form@id(loginForm)@submit(handleLogin):
    field:
      label:
        Email
      .input@type(email)@id(email)@required

    actions:
      .btn-primary@id(loginBtn)(Sign in)
      .btn-ghost@click(handleForgot)(Forgot password?)

That compiles to:

<main class="mdl-page">
  <div class="mdl-hero">
    <h2>Sign in</h2>
    <p>Welcome back.</p>
  </div>
  <form class="mdl-form" id="loginForm" data-mdl-on-submit="handleLogin">
    <div class="mdl-field">
      <label class="mdl-label">Email</label>
      <input class="mdl-input" type="email" id="email" required>
    </div>
    <div class="mdl-actions">
      <button class="mdl-btn-primary" id="loginBtn">Sign in</button>
      <button class="mdl-btn-ghost" data-mdl-on-click="handleForgot">Forgot password?</button>
    </div>
  </form>
</main>

Clean, semantic HTML. No divs you didn't ask for. No inline styles. Every element has a predictable .mdl-* class that CSS can target.

How CSS and JS talk to it

CSS targets .mdl-* classes directly. No configuration needed.

JS uses standard DOM APIs. The @id() attribute compiles to a real HTML id. The @submit() and @click() attributes wire events to functions in your external JS file.

// scripts/auth.js
export async function handleLogin(e) {
  e.preventDefault()
  const email = document.querySelector('#email').value
  // your logic here
}

No framework. No runtime. No magic. Just the platform.

How to install

npm install -g @tosiiko/mdl
mdl --help

The CLI is a prebuilt Rust binary. Fast, no dependencies, works on Mac, Linux, and Windows.

DEV Community: Tosiiko

Every MDL behavior attribute for htmx and TypeScript

Enable the htmx adapter

htmx behavior attribute map

Supported @api(...) methods

Supported @swap(...) values

Supported @trigger(...) values

Supported @encoding(...) values

Supported @sync(...) strategies

Supported @inherit(...) and @disinherit(...) names

Configure TypeScript handlers

TypeScript event attributes

Complete event alias list

TypeScript handler example

General MDL attribute rules

Try the examples

Links

MDL 0.1.9: optional TypeScript behavior scripts without a TypeScript project setup

What changed

TypeScript trees are supported

What MDL does not do

Inline scripts stay JavaScript for now

Event bindings still work the same way

New example: examples/typescript

Why this shape?

Try MDL

Links

MDL 0.1.8: htmx examples, safer npm binaries, and portable static builds

New: Complete htmx Example App

Behavior Adapters

Safer npm Package

Portable Static Builds

Try MDL

Links

# Next MDL Update: Security-First Adapters and HTMX Support

Why adapters?

I Built MDL: A Small Language for Writing Static Websites as Readable Outlines

What MDL Looks Like

Why I Built It

The Browser Platform Stays Visible

Getting Started

CLI Commands

Recent Improvements

Where I Think MDL Fits

Feedback Welcome

Links

What's coming in MDL 0.1.3 — source maps, metadata, diagnostics, and more

What's already shipped in 0.1.x

Source maps

Document metadata

Better diagnostics

Multi-app workspaces

Advanced browser primitives

What I'm building toward

Try it now

npm i @tosiiko/mdl

I built MDL — a tiny authoring language so you never write raw HTML again

The problem

What I built

What it looks like

How CSS and JS talk to it

How to install

Links

Supported `@api(...)` methods

Supported `@swap(...)` values

Supported `@trigger(...)` values

Supported `@encoding(...)` values

Supported `@sync(...)` strategies

Supported `@inherit(...)` and `@disinherit(...)` names

New example: `examples/typescript`