MDL Documentation

Start here

MDL is a tiny authoring language for people who want static web pages that stay readable at the source level. You write .mdl files for structure and content, keep layout in CSS, add JavaScript only for behavior, and compile everything to normal HTML.

.mdl  -> structure and content
        .json -> project manifest
        .css  -> layout and design
        .js   -> behavior when needed
        HTML  -> compiler output

The fastest path is:

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

Open http://127.0.0.1:3999, edit apps/my-mdl-site/pages/index.mdl, then run mdl check, mdl format --check, and mdl build before publishing.

Choose your next page

New project

Use the install guide for npm setup, local activation, the created folder structure, and first edits.

Install MDL

Writing pages

Use the language guide for sections, Markdown, dot elements, attributes, scripts, and UI patterns.

Read language

Project settings

Use the config guide for mdl.json, CSS bundles, metadata, scripts, assets, and multi-page builds.

Configure projects

Commands

Use the CLI reference for init, new, check, format, build, serve, and spec-test.

Use the CLI

Examples

Copy small snippets for heroes, grids, forms, tabs, Tailwind classes, and mounted elements.

Browse examples

Shipping

Build static output and deploy the dist/ folder to GitHub Pages or another static host.

Deploy a site

Mental model

MDL keeps the web platform visible. It gives common page structures short names, adds predictable mdl-* classes, and then gets out of the way.

pricing:
    card:
      ## Starter
      $9/month
      .btn-primary(Choose)

That compiles to plain HTML:

<div class="mdl-pricing">
    <div class="mdl-card">
      <h2>Starter</h2>
      <p>$9/month</p>
      <button class="mdl-btn-primary">Choose</button>
    </div>
  </div>

You still write normal CSS against .mdl-pricing, .mdl-card, and any author classes you add with @class(...).

Daily workflow

Create or choose an app

Run mdl init in the current folder, mdl new my-site for a fresh folder, or mdl init --app admin --port 4001 to add another app to a workspace.
Edit source files

Put pages in pages/, styles in css/, scripts in scripts/, and images or static files in assets/.
Check early

Run mdl check for parse, config, route, asset, and accessibility-oriented diagnostics.
Format consistently

Run mdl format to rewrite sources, or mdl format --check in CI.
Preview and build

Use mdl serve while editing, then mdl build to write static HTML, copied assets, CSS bundles, manifests, and source-map sidecars.

What gets generated

A standard scaffold creates one app under apps/<name>/. Building that app writes static files to the configured output folder.

apps/my-mdl-site/pages/index.mdl  -> apps/my-mdl-site/dist/index.html
        apps/my-mdl-site/css/*.css        -> apps/my-mdl-site/dist/app.css
        apps/my-mdl-site/scripts/app.js   -> apps/my-mdl-site/dist/scripts/app.js
        apps/my-mdl-site/assets/*         -> apps/my-mdl-site/dist/assets/*

The output is static. You can upload it to any host that serves HTML, CSS, JavaScript, and assets.

Package behavior

The public npm package is @tosiiko/mdl. It does not use npm install scripts, so project files are created only when you run npm exec -- mdl init, mdl init, or mdl new.

MDL docs