DEV Community

Tosiiko
Tosiiko

Posted on

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

#webdev #staticweb #markdown #tooling

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.
Enter fullscreen mode Exit fullscreen mode

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>
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Then open:

http://127.0.0.1:3999
Enter fullscreen mode Exit fullscreen mode

CLI Commands 

mdl init
mdl new my-site
mdl check
mdl format
mdl build
mdl serve
Enter fullscreen mode Exit fullscreen mode

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"
  }
}
Enter fullscreen mode Exit fullscreen mode

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

For root-domain hosting:

{
  "routing": {
    "links": "root"
  }
}
Enter fullscreen mode Exit fullscreen mode

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

Package:

npm install @tosiiko/mdl
Enter fullscreen mode Exit fullscreen mode

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

Top comments (0)