Quick start

Create a new site with create-bongo, or add bongo to an existing project by hand. Both paths end with a dev server on your machine and a built site in public/.

Create a site

Give create-bongo the name of the new folder:

bun create bongo my-site

Install the packages and start the dev server:

cd my-site
bun install
bun run dev

The dev server prints its URL, which is http://localhost:3000/ by default. See Dev server.

To build the site into public/:

bun run build

Starter files

The new folder holds a small blog:

my-site/
├── assets/
│   ├── main.ts
│   └── style.css
├── content/
│   ├── blog/
│   │   ├── index.hbs
│   │   └── welcome.md
│   ├── about.md
│   ├── contact.md
│   └── index.md
├── layouts/
│   ├── blog/
│   │   ├── index.hbs
│   │   └── single.hbs
│   └── html.hbs
├── partials/
│   ├── footer.hbs
│   ├── nav.hbs
│   └── postmeta.hbs
├── .editorconfig
├── .gitignore
├── bongo.config.ts
├── package.json
└── tsconfig.json

The blog in content/blog/ has more posts than this tree shows. Project layout describes each folder.

The package.json has two scripts, and installs bongo, @bongo/markdown, and shiki as dev dependencies:

{
  "private": true,
  "scripts": {
    "dev": "bongo dev",
    "build": "bongo build"
  },
  "devDependencies": {
    "@bongo/markdown": "latest",
    "bongo": "npm:@bongo/bongo",
    "shiki": "^4.0.2"
  }
}

create-bongo options

bun create bongo my-site --force
bun create bongo my-site -C ../sites
bun create bongo --help

Without --force, create-bongo refuses to write into a folder that exists, and stops with Refusing to overwrite existing "my-site" directory.

Add bongo by hand

Install

Install bongo through its bongo alias, and the Markdown plugin:

bun add bongo@npm:@bongo/bongo
bun add @bongo/markdown

Add a config

Create bongo.config.ts in the project folder:

import { markdown } from '@bongo/markdown';

export default {
	$site: {
		title: 'My Site',
		url: 'https://example.com/',
		lang: 'en',
	},
	plugins: [
		markdown(),
	],
};

See Config for all fields.

Add a layout

Every page needs a layouts/html.hbs. It prints the page inside an HTML document:

<!doctype html>
<html lang="{{ $site.lang }}">
<head>
  <meta charset="utf-8"/>
  <title>{{ $page.title }}</title>
</head>
<body>
  {{{ $page.content }}}
</body>
</html>

See Templates for layouts and template values.

Add a page

Create content/index.md:

---
title: Home
---

# Hello

See Content for page files and URLs.

Run it

Start the dev server:

bunx bongo dev

Build the site into public/:

bunx bongo build

To run them as bun run dev and bun run build, add the two scripts from the starter files to your package.json.

Next steps

• Project layout: learn what each folder does.
• CLI: see every command and option.
• Templates: add styles, scripts, and assets to your layout.