Quickstart

Create a site with the CLI, then use its package scripts for everyday work. Each repo owns its dependencies, commands, and Plugin activation in package.json.

You need Bun 1.4 or newer. See Install if you need it.

bunx @pathmx/core@beta init my-site

You should see Created PathMX project in … after dependencies install. The directory must be empty or absent. bunx runs the scaffolder without a global CLI install; the new project pins the Core version it uses. If you used the shell installer, pmx init my-site also works.

cd my-site
bun run dev

You should see a listen line with url=http://0.0.0.0:3000/. Open http://localhost:3000 for the welcome page. Use bun run dev --port 3001 or the PORT variable to change the port.

Update paths/index.md and save:

[@layout.default]: ./site.layout.md

# My site

Hello from PathMX.

The open browser tab updates without a reload. Keep the default layout declaration to retain the starter layout's reference sidebar and overlay destinations.

Create paths/about.md beside the home page:

# About

Back to [home](./index.md).

You should see it at /about.page. Relative links to .md files render as canonical routes, so they also work on GitHub and in editors.

bun run check
bun run pmx tree

check reports No issues found, and tree lists both pages with their type and Block count. Both use the project's installed Core.

The generated package.json pins @pathmx/core and includes these scripts:

{
  "scripts": {
    "dev": "pmx dev",
    "start": "pmx serve",
    "check": "pmx lint",
    "typecheck": "tsc --noEmit"
  }
}

bun run dev watches the site and keeps the browser in sync. bun run start runs the production server. Bun resolves pmx from the installed project packages. Add project-specific flags, such as a preferred port, to these scripts. The typecheck script checks TypeScript when you add custom Plugins or Actions.

Commit package.json, bun.lock, and the authored files. Someone cloning the repo only needs Bun:

bun install --frozen-lockfile
bun run dev

For other CLI commands, use bun run pmx <command>. If you have the global launcher, pmx <command> also delegates project commands to the pinned Core.

Add optional packages with bun run pmx plugins add player, for example. This updates both the dependency and pathmx.plugins activation in the manifest. See Packages for configured Plugins.

Build a workshop site adds a shared layout, menu, styles, and a reusable component. See Project structure for the file and route conventions.