[@layout]: ../docs.layout.md

# 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](./install.guide.md) if you need it.

---

## 1. Create the project

```sh
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.

---

## 2. Start the development server

```sh
cd my-site
bun run dev
```

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

---

## 3. Edit the home page

Update `paths/index.md` and save:

```md
[@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.

---

## 4. Add a second page

Create `paths/about.md` beside the home page:

```md
# 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.

---

## 5. Check the project

```sh
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 project owns the setup

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

```json
{
  "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:

```sh
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](../packages.reference.md#install-and-activate) for configured Plugins.

## Next

[Build a workshop site](./build-a-site.guide.md) adds a shared layout, menu,
styles, and a reusable component. See [Project structure](./project-structure.guide.md)
for the file and route conventions.