baybay▮v1.4.2

Docs / Guides / Getting Started

Getting Started

This tutorial takes you from an empty terminal to a deployed site. It should take about ten minutes, most of which is reading.

Prerequisites

You need exactly two things:

  • Node.js 18 or newer. Check with node --version.
  • A terminal. Any shell works — the examples below use a POSIX prompt, but every command is identical on Windows.

No global build tools, no Python, no Ruby. If you can run npm, you can run Baybay.

1. Install the CLI

Baybay ships as a single npm package with zero runtime dependencies:

shell
$ npm install -g baybay
added 1 package in 3.1s

Verify the install:

shell
$ baybay --version
baybay/1.4.2 node/v20.11.1 (darwin-arm64)
Note

Prefer project-local installs? npx baybay works for every command in these docs — nothing below assumes a global install.

2. Scaffold a project

baybay new creates a minimal, working site. It asks no questions unless you pass --template:

shell
$ baybay new my-site
✔ Created my-site/
✔ Wrote 7 files (default template)

  my-site/
  ├── baybay.config.js
  ├── src/
  │   ├── index.md
  │   ├── about.md
  │   └── _layout.html
  ├── static/
  │   └── style.css
  ├── package.json
  └── .gitignore

  next:  cd my-site && baybay dev

Every file in the scaffold is meant to be read and edited. There is no hidden machinery: src/ holds your content, _layout.html wraps every page, and static/ is copied to the output verbatim.

3. Run the dev server

From inside the project folder:

shell
$ cd my-site && baybay dev
baybay v1.4.2  dev server

  ➜ Local:    http://localhost:8484/
  ➜ Network:  http://192.168.1.24:8484/

  built 2 pages in 38 ms · watching src/ and static/

Open http://localhost:8484 and leave the server running. Every save triggers an incremental rebuild — only the changed page is recompiled, and the browser swaps content in place without a full reload.

Tip

Port taken? Pass --port 3000, or set dev.port in your config file to make it permanent.

4. Write your first page

Pages are Markdown files with YAML front matter. Create src/guides/hello.md:

markdown
---
title: Hello, Baybay
description: My first page.
---

# Hello, Baybay

Routes mirror the `src/` tree, so this file becomes
`/guides/hello/` — no route config needed.

- Front matter fields are available in the layout as `{{ page.title }}`.
- Relative links between `.md` files are rewritten to final URLs.

Save the file and the dev server logs the rebuild:

shell
[12:04:31] src/guides/hello.md changed
[12:04:31] ✔ rebuilt 1 page in 12 ms → /guides/hello/

How routing works

Baybay maps files to clean URLs with three rules:

  • src/index.md → /
  • src/about.md → /about/
  • src/guides/hello.md → /guides/hello/

Files and folders starting with _ (like _layout.html) are never emitted — they are templates and partials only.

5. Build for production

When you are ready to ship, produce the static output:

shell
$ baybay build
baybay v1.4.2  production build

  ✔ 3 pages compiled
  ✔ 1 asset copied from static/
  ✔ HTML minified, sitemap.xml written

  dist/ · 3 pages · 14.2 kB total · 61 ms

Everything lands in dist/ (configurable via outDir). The output is plain HTML and assets — you can host it on anything that serves files.

6. Deploy

The fastest path is the built-in deployer, which builds first and then pushes dist/ to a target:

shell
$ baybay deploy --target netlify
✔ Built 3 pages in 59 ms
✔ Uploaded 4 files (14.2 kB) to Netlify

  ➜ Live: https://my-site-8f3a1c.netlify.app

  deployed in 9.4 s

Supported targets are netlify, vercel, gh-pages, and rsync. See the baybay deploy reference for flags and credentials.

Prefer your own pipeline? Skip deploy entirely — run baybay build in CI and publish dist/ however you like.

Next steps