@tosiiko/mdl

MDL is a small authoring language for building clean HTML without writing raw HTML by hand. Write .mdl files, add normal CSS and JavaScript, then use the mdl CLI to check, build, and serve the project.

Quick Start

Install inside a project folder:

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

A local install runs mdl init --quiet when starter files are missing, so the folder is immediately ready for development. bin/activate adds the local node_modules/.bin folder to your shell path for this project.

Skip automatic initialization when you only want the package installed:

MDL_SKIP_INIT=1 npm install @tosiiko/mdl

Install globally when you want mdl available everywhere:

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

What mdl init Creates

my-mdl-site/
  mdl.json
  README.md
  .gitignore
  bin/
    activate
  pages/
    index.mdl
  css/
    main.css
    layout.css
    components.css
  scripts/
    app.js
  assets/
    mdl-logo-tagline-light.png

The generated site works immediately:

mdl check
mdl build
mdl serve

mdl serve starts the dev server on http://127.0.0.1:3999, watches pages/, css/, scripts/, and assets/, and rebuilds when files change.

Starter Page

page:
  hero:
    .img@src(assets/mdl-logo-tagline-light.png)@alt(MDL logo)
    # my-mdl-site
    Built with MDL.

  nav:
    .link(home)

  section:
    ## Get started

    Edit `pages/index.mdl` to build your page.
    Style it in `css/components.css`.

Project Config

Commands without an explicit .mdl file read mdl.json from the current directory. MDL supports // and /* ... */ comments in config files so unused areas can stay visible without becoming active.

{
  "name": "my-mdl-site",

  // If this config lives above your site folder, uncomment root.
  // "root": "site",

  "entry": "pages/index.mdl",
  "pages": "pages",
  "output": "dist",
  "css": {
    "runtime": true,
    "bundle": "dist/app.css"
  },
  "styles": [
    "css/main.css",
    "css/layout.css",
    "css/components.css"
    // , "css/theme.css"
  ],
  "head_scripts": [
    // "https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"
  ],
  "scripts": [
    "scripts/app.js"
    // , "scripts/analytics.js"
  ],
  "assets": [
    "assets"
  ],
  "title": "my-mdl-site",
  "port": 3999
}

Commands

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

mdl init initializes the current folder. mdl new my-mdl-site creates a new folder and runs the same scaffold logic inside it.

Without mdl.json, pass a file directly:

mdl check pages/index.mdl
mdl build pages/index.mdl --style css/main.css
mdl serve pages/index.mdl

Package Contents

This npm package exposes the mdl command and runs the prebuilt Rust binary for your operating system and CPU. The small bin/mdl.js launcher selects the correct binary at runtime.

The public package contains:

bin/mdl.js
scripts/postinstall.mjs
vendor/darwin-arm64/mdl
vendor/darwin-x64/mdl
vendor/linux-arm64/mdl
vendor/linux-x64/mdl
vendor/win32-x64/mdl.exe
README.md
LICENSE-APACHE
SHASUMS256.txt

SHASUMS256.txt lists the SHA-256 checksum for each published file.

Troubleshooting

If mdl is not found after a local install, activate the project shell:

source bin/activate

You can also run the local binary through npm:

npm exec -- mdl check
npm exec -- mdl serve

If the starter files were skipped or deleted, recreate them:

mdl init --force

License

The package is published with the MIT OR Apache-2.0 license expression and includes the Apache License 2.0 text in LICENSE-APACHE.