Configure mdl.json

Sample config

The generated config is valid plain JSON, so editors and package scanners can read it without JSONC support.

{
          "name": "my-mdl-site",
          "lang": "en",
          "title": "my-mdl-site",
          "description": "Built with MDL.",
          "favicon": "assets/mdl-logo-tagline-light.png",
          "viewport": "width=device-width, initial-scale=1",
          "meta": [],
          "links": [],
          "entry": "pages/index.mdl",
          "pages": "pages",
          "output": "dist",
          "css": {
            "runtime": true,
            "bundle": "dist/app.css"
          },
          "routing": {
            "links": "root"
          },
          "styles": [
            "css/main.css",
            "css/layout.css",
            "css/components.css"
          ],
          "head_scripts": [],
          "scripts": [
            "scripts/app.js"
          ],
          "assets": [
            "assets"
          ],
          "port": 3999
        }
        

Important fields

Path rules

Paths are resolved from the directory that contains mdl.json, unless root is set.

{
          "root": ".",
          "pages": "pages",
          "output": "dist",
          "styles": ["css/main.css"],
          "assets": ["assets"]
        }
        

In the generated workspace, each app owns its config:

apps/my-mdl-site/mdl.json
        apps/my-mdl-site/pages/index.mdl
        apps/my-mdl-site/dist/index.html
        

When a workspace contains multiple apps, pass the app folder to commands such as mdl build apps/admin.

Document metadata

Config values populate the document head for every page in the project.

{
          "lang": "en",
          "title": "My MDL Site",
          "description": "A static site built with MDL.",
          "canonical": "https://example.com/",
          "favicon": "assets/icon.png",
          "viewport": "width=device-width, initial-scale=1",
          "meta": [
            { "name": "theme-color", "content": "#172033" }
          ],
          "links": [
            { "rel": "preconnect", "href": "https://fonts.googleapis.com" }
          ]
        }
        

Use social when you want Open Graph and Twitter card tags generated from one preset.

CSS runtime and bundles

styles lists the stylesheets you author. css.runtime adds the small MDL runtime stylesheet, and css.bundle chooses where the combined CSS file is written.

{
          "css": {
            "runtime": true,
            "bundle": "dist/app.css"
          },
          "styles": [
            "css/main.css",
            "css/layout.css",
            "css/components.css"
          ]
        }
        

Set "runtime": false when you want to provide every base style yourself.

Routing links

routing.links controls how mdl build writes local root-relative links in generated HTML.

Keep the default when the site is served from a domain root:

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

Use relative links when the built files may be opened directly, uploaded inside a subfolder, or served from a path such as /getmdl/:

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

Relative mode rewrites local URLs such as /, /docs.html, and /assets/logo.png to paths that work from each output page. External URLs, protocol-relative URLs, and #section anchors are left alone.

Scripts

head_scripts are classic scripts placed in the document head. scripts are JavaScript modules loaded for event handlers and mount handlers.

{
          "head_scripts": [
            "https://cdn.tailwindcss.com"
          ],
          "scripts": [
            "scripts/app.js"
          ]
        }
        

Module scripts can export functions referenced from MDL attributes such as @click(handleClick), @submit(handleSubmit), and @mount(drawScene).

Multi-page builds

mdl build compiles every .mdl file under pages and preserves nested folders.

pages/index.mdl       -> dist/index.html
        pages/docs.mdl        -> dist/docs.html
        pages/guides/intro.mdl -> dist/guides/intro.html
        

Asset copying

Add folders or files to assets and MDL copies them into dist.

{
          "assets": [
            "assets",
            "CNAME"
          ]
        }
        

This docs site uses that path to publish the logo and the getmdl.site CNAME file.

Validation

Run checks after changing config:

mdl check
        mdl check --json
        

MDL reports missing pages, bad paths, route mismatches, missing linked assets, missing form controls, duplicate ids, and invalid references before you build.