MDL Documentation

Requirements

MDL ships as the @tosiiko/mdl npm package with prebuilt CLI binaries for common desktop and CI platforms.

Check that Node and npm are available:

node --version
        npm --version

Use a local install for site projects so each workspace can pin its own MDL version. Use a global install only when you want mdl available everywhere.

Local install

Local install is the best default for a project:

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

The package does not run install scripts. npm exec -- mdl init creates the starter files explicitly. source bin/activate adds node_modules/.bin to the current shell so mdl works without typing npm exec.

Open http://127.0.0.1:3999 after the server starts.

Global install

A global install is useful for quick experiments and one-off generators:

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

If a project also has a local install, prefer the local version inside that project so teammates and CI use the same CLI.

Workspace apps

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

Add another app to the same workspace with a separate config, source tree, output folder, and port:

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

When a workspace has more than one app, pass the app folder to commands:

mdl check apps/admin
        mdl build apps/admin
        mdl serve apps/admin

Created folder structure

mdl init creates a server-ready project:

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

The app config lives inside apps/my-mdl-site/, so a single installed workspace can host multiple MDL apps.

First edit

Change the starter page:

apps/my-mdl-site/pages/index.mdl

Then adjust the component styling:

apps/my-mdl-site/css/components.css

Run checks before building:

mdl check
        mdl format --check
        mdl build

Verify the install

These commands should succeed after activation:

mdl --help
        mdl check
        mdl build
        mdl serve

mdl check validates source syntax, config paths, routes, assets, form labels, ARIA references, and similar project details. mdl build writes static output to the configured dist folder.

Troubleshooting

If mdl is not found after local install:

source bin/activate

You can also run through npm:

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

If starter files were skipped or deleted:

mdl init --force

If you want package scripts in package.json, ask the scaffold to add missing defaults:

mdl init --package-scripts
        npm run check
        npm run build
        npm run serve

Install MDL